{ "openapi": "3.1.0", "info": { "title": "Kapso Platform API", "version": "0.2.0", "description": "Build WhatsApp messaging into your product. Manage customers, connect phone numbers, send broadcasts, and handle conversations.\n" }, "servers": [ { "url": "https://api.kapso.ai/platform/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Customers", "description": "Manage customer accounts" }, { "name": "Setup Links", "description": "WhatsApp onboarding via embedded signup" }, { "name": "Phone Numbers", "description": "Connect and manage WhatsApp numbers" }, { "name": "Webhooks", "description": "Subscribe to WhatsApp events" }, { "name": "Display Names", "description": "Update WhatsApp business display names" }, { "name": "Broadcasts", "description": "Send template messages at scale\n\n**Alpha**: This API is in alpha and subject to change\n" }, { "name": "Conversations", "description": "Manage conversation state" }, { "name": "Media", "description": "Upload media files for WhatsApp messaging" }, { "name": "Users", "description": "Manage project team members" }, { "name": "Inbox Embeds", "description": "Create and manage embeddable inbox access links" }, { "name": "Webhook Deliveries", "description": "View webhook delivery attempts and their status" }, { "name": "External API Logs", "description": "View logs of external API calls made by the project" }, { "name": "Log Search", "description": "Search log events across API, Meta, workflow, and webhook sources" }, { "name": "Events", "description": "Emit and query project-scoped events" }, { "name": "Provider Models", "description": "List available AI provider models" }, { "name": "WhatsApp Flows", "description": "Build interactive WhatsApp Flows for surveys and forms" }, { "name": "Contacts", "description": "Manage WhatsApp contacts" }, { "name": "Findings", "description": "Detect recurring problems in conversations and investigate them with AI" }, { "name": "Notifications", "description": "Route project alerts to shared inboxes and Slack channels connected from the Kapso app" }, { "name": "WhatsApp Funding", "description": "Read Kapso funding status and recorded messaging and calling usage, and stop portfolio funding" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "NotificationEventType": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable identifier used when creating routes, e.g. `findings.detected`." }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "enum": [ "account", "billing", "usage", "whatsapp", "workflow", "agent", "integration", "security", "reports", "product", "findings" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "critical" ] }, "supported_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "slack" ] } }, "data_contract": { "type": "object", "description": "Fields the event payload may carry. Every event accepts `title`, `message`,\n`resource_name`, `details`, and `occurred_at`; `kapso_agent.*` events also carry\n`agent_run_id`.\n", "properties": { "required": { "type": "array", "items": { "type": "string" } }, "optional": { "type": "array", "items": { "type": "string" } } } }, "surface_path_template": { "type": "string", "description": "Kapso app path the notification links to, with `%s` interpolated." } } }, "NotificationDestination": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "shared_email", "slack_channel" ] }, "label": { "type": "string", "nullable": true, "description": "Display name. For `slack_channel` destinations this is the channel name." }, "status": { "type": "string", "enum": [ "pending", "active", "unhealthy" ], "description": "A `shared_email` destination is created as `pending` and becomes `active` once the\nrecipient opens the verification link. Slack destinations are `active` on creation\nand become `unhealthy` when the channel can no longer be posted to. Removed\ndestinations are disabled and no longer listed.\n" }, "channel": { "type": "string", "enum": [ "email", "slack" ] }, "address": { "type": "string", "description": "Email address, or Slack channel ID for `slack_channel` destinations." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "slack_channel_binding_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Kapso Agent channel binding, or `null` for channels connected only for notifications." }, "workspace_name": { "type": "string", "nullable": true, "description": "Slack workspace name, when the destination is a Slack channel." }, "user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Always `null` for team destinations." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "NotificationRoute": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "destination_id": { "type": "string", "format": "uuid" }, "event_key": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FindingsErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "findings_not_enabled", "finding_not_found", "investigation_unavailable" ], "description": "Machine-readable reason. Present on both `404` cases and on an ineligible\ninvestigation. Absent on validation and pagination errors.\n" } } }, "FindingSummaryInvestigation": { "type": "object", "required": [ "status", "retryable", "retry_reason", "completed_at", "error_message", "cause_title", "summary" ], "properties": { "status": { "type": "string", "enum": [ "queued", "investigating", "completed", "failed", "timed_out" ] }, "retryable": { "type": "boolean", "description": "Whether a new investigation can be started for this finding." }, "retry_reason": { "type": [ "string", "null" ], "description": "Why a retry is available, when it is." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ], "description": "Truncated to 200 characters." }, "cause_title": { "type": [ "string", "null" ], "description": "Title of the top cause, truncated to 100 characters." }, "summary": { "type": [ "string", "null" ], "description": "Investigation summary, truncated to 200 characters." } } }, "FindingSummaryVerification": { "type": "object", "required": [ "status", "trigger_type", "completed_at" ], "properties": { "status": { "type": "string", "enum": [ "monitoring", "resolved", "not_improved", "dismissed" ] }, "trigger_type": { "type": "string", "enum": [ "workflow_version", "regression", "manual" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "FindingSummary": { "type": "object", "required": [ "id", "signal_name", "direction", "status", "affected_count", "affected_unit", "last_observed_at", "related_findings_count", "investigation", "verification" ], "properties": { "id": { "type": "string", "format": "uuid" }, "signal_name": { "type": "string", "description": "Project event name behind the finding.", "example": "conversation.user_frustrated" }, "direction": { "type": "string", "enum": [ "rising", "falling", "recurring" ] }, "status": { "type": "string", "enum": [ "candidate", "open" ], "description": "Listing only returns `candidate` and `open` findings. Quiet findings are\nreachable through `GET /findings/{finding_id}`.\n" }, "affected_count": { "type": "integer" }, "affected_unit": { "type": "string", "enum": [ "conversations", "events" ] }, "last_observed_at": { "type": "string", "format": "date-time" }, "related_findings_count": { "type": "integer", "description": "Number of other findings grouped with this one." }, "investigation": { "oneOf": [ { "$ref": "#/components/schemas/FindingSummaryInvestigation" }, { "type": "null" } ] }, "verification": { "oneOf": [ { "$ref": "#/components/schemas/FindingSummaryVerification" }, { "type": "null" } ] } } }, "FindingListResponse": { "type": "object", "required": [ "data", "paging" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FindingSummary" } }, "paging": { "type": "object", "required": [ "cursors", "next", "previous" ], "properties": { "cursors": { "type": "object", "required": [ "before", "after" ], "properties": { "before": { "type": [ "string", "null" ], "description": "Opaque cursor (Base64 encoded) for the first item on this page." }, "after": { "type": [ "string", "null" ], "description": "Opaque cursor (Base64 encoded) for the last item on this page." } } }, "next": { "type": [ "string", "null" ], "description": "Opaque cursor, not a URL. Pass it back as `after` to fetch the next page.\n`null` when this is the last page.\n" }, "previous": { "type": [ "string", "null" ], "description": "Opaque cursor, not a URL. Pass it back as `before` to fetch the previous page.\n`null` when this is the first page.\n" } } } } }, "FindingEvidenceReference": { "type": "object", "required": [ "source_type", "source_id", "observation", "occurred_at" ], "properties": { "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "observation": { "type": [ "string", "null" ] }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "FindingCause": { "type": "object", "required": [ "title", "explanation", "confidence", "evidence_references" ], "properties": { "title": { "type": "string" }, "explanation": { "type": "string" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "evidence_references": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceReference" } } } }, "FindingSuggestedFix": { "type": "object", "required": [ "title", "priority", "category", "change", "verification", "target", "evidence_references" ], "properties": { "title": { "type": "string" }, "priority": { "type": "string", "enum": [ "primary", "secondary" ], "description": "Exactly one suggested fix per investigation is `primary`." }, "category": { "type": "string", "enum": [ "workflow", "code", "evaluation", "configuration" ], "description": "What kind of thing has to change." }, "change": { "type": "string", "description": "What to change." }, "verification": { "type": "string", "description": "How to verify the fix." }, "target": { "type": "object", "required": [ "name", "location" ], "properties": { "name": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } } }, "evidence_references": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceReference" } } } }, "FindingInvestigationResult": { "type": "object", "required": [ "summary", "alternative_explanations", "coverage_limitations", "affected_components", "causes", "suggested_fixes" ], "properties": { "summary": { "type": [ "string", "null" ] }, "alternative_explanations": { "type": [ "array", "null" ], "items": { "type": "string" } }, "coverage_limitations": { "type": [ "array", "null" ], "items": { "type": "string" } }, "affected_components": { "type": [ "array", "null" ], "items": { "type": "string" } }, "causes": { "type": "array", "items": { "$ref": "#/components/schemas/FindingCause" } }, "suggested_fixes": { "type": "array", "items": { "$ref": "#/components/schemas/FindingSuggestedFix" } }, "change_since_previous": { "type": "object", "description": "Present when the investigation was a retry that only looked at evidence newer than\nthe previous investigation. Describes how the conclusion changed.\n", "required": [ "explanation" ], "properties": { "status": { "type": "string", "enum": [ "not_applicable", "unchanged", "narrowed", "revised", "replaced", "insufficient_evidence" ] }, "explanation": { "type": "string", "maxLength": 300 } } } } }, "FindingInvestigation": { "type": "object", "required": [ "id", "status", "retryable", "retry_reason", "error_message", "created_at", "completed_at", "workflow_id", "workflow_name", "result" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "investigating", "completed", "failed", "timed_out" ] }, "retryable": { "type": "boolean" }, "retry_reason": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "workflow_name": { "type": [ "string", "null" ] }, "result": { "$ref": "#/components/schemas/FindingInvestigationResult" } } }, "FindingVerification": { "type": "object", "required": [ "id", "status", "trigger_type", "from_workflow_version", "to_workflow_version", "started_at", "completed_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "monitoring", "resolved", "not_improved", "dismissed" ] }, "trigger_type": { "type": "string", "enum": [ "workflow_version", "regression", "manual" ] }, "from_workflow_version": { "type": [ "integer", "null" ] }, "to_workflow_version": { "type": [ "integer", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "RelatedFinding": { "type": "object", "required": [ "id", "source_type", "source_key", "signal_name", "direction", "affected_count", "baseline_count", "current_rate", "baseline_rate", "window_start_at", "window_end_at", "affected_unit", "evidence_revision" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source_type": { "type": "string", "enum": [ "project_event" ] }, "source_key": { "type": "string" }, "signal_name": { "type": "string" }, "direction": { "type": "string", "enum": [ "rising", "falling", "recurring" ] }, "affected_count": { "type": "integer" }, "baseline_count": { "type": [ "integer", "null" ] }, "current_rate": { "type": [ "number", "null" ], "description": "Share of conversations in the current window, from 0 to 1." }, "baseline_rate": { "type": [ "number", "null" ] }, "window_start_at": { "type": "string", "format": "date-time" }, "window_end_at": { "type": "string", "format": "date-time" }, "affected_unit": { "type": "string", "enum": [ "conversations", "events" ] }, "evidence_revision": { "type": "integer" } } }, "FindingDetail": { "type": "object", "required": [ "id", "source_type", "source_key", "signal_name", "direction", "status", "affected_count", "baseline_count", "current_rate", "baseline_rate", "evidence_revision", "last_observed_at", "window_start_at", "window_end_at", "last_qualified_at", "affected_unit", "workflow_id", "workflow_name", "verification", "related_findings", "investigation" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source_type": { "type": "string", "enum": [ "project_event" ] }, "source_key": { "type": "string" }, "signal_name": { "type": "string" }, "direction": { "type": "string", "enum": [ "rising", "falling", "recurring" ] }, "status": { "type": "string", "enum": [ "candidate", "open", "quiet" ] }, "affected_count": { "type": "integer" }, "baseline_count": { "type": [ "integer", "null" ] }, "current_rate": { "type": [ "number", "null" ], "description": "Share of conversations in the current window, from 0 to 1." }, "baseline_rate": { "type": [ "number", "null" ] }, "evidence_revision": { "type": "integer", "description": "Increments when new qualifying evidence arrives." }, "last_observed_at": { "type": "string", "format": "date-time" }, "window_start_at": { "type": "string", "format": "date-time" }, "window_end_at": { "type": "string", "format": "date-time" }, "last_qualified_at": { "type": "string", "format": "date-time" }, "affected_unit": { "type": "string", "enum": [ "conversations", "events" ] }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "workflow_name": { "type": [ "string", "null" ] }, "verification": { "oneOf": [ { "$ref": "#/components/schemas/FindingVerification" }, { "type": "null" } ] }, "related_findings": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedFinding" } }, "investigation": { "oneOf": [ { "$ref": "#/components/schemas/FindingInvestigation" }, { "type": "null" } ] } } }, "FindingDetailResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FindingDetail" } } }, "FindingEvidenceFinding": { "type": "object", "required": [ "id", "source_type", "source_key", "signal_name", "direction", "status", "window_start_at", "window_end_at", "affected_count", "baseline_count", "current_rate", "baseline_rate", "last_observed_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source_type": { "type": "string", "enum": [ "project_event" ] }, "source_key": { "type": "string" }, "signal_name": { "type": "string" }, "direction": { "type": "string", "enum": [ "rising", "falling", "recurring" ] }, "status": { "type": "string", "enum": [ "candidate", "open", "quiet" ] }, "window_start_at": { "type": "string", "format": "date-time" }, "window_end_at": { "type": "string", "format": "date-time" }, "affected_count": { "type": "integer" }, "baseline_count": { "type": [ "integer", "null" ] }, "current_rate": { "type": [ "number", "null" ] }, "baseline_rate": { "type": [ "number", "null" ] }, "last_observed_at": { "type": "string", "format": "date-time" } } }, "FindingEvidenceEventDefinition": { "type": "object", "required": [ "id", "name", "display_name", "description", "property_schema" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "property_schema": { "type": [ "object", "null" ], "additionalProperties": true } } }, "FindingEvidenceDailyHistoryEntry": { "type": "object", "required": [ "bucket_on", "event_count", "conversation_count" ], "properties": { "bucket_on": { "type": "string", "format": "date" }, "event_count": { "type": "integer" }, "conversation_count": { "type": "integer" } } }, "FindingEvidenceSourceEvent": { "type": "object", "required": [ "id", "name", "observed_at", "occurred_at", "conversation_id", "properties", "whatsapp_config", "source_workflow" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time", "description": "When Kapso recorded the evidence. Used to order retry deltas." }, "occurred_at": { "type": "string", "format": "date-time" }, "conversation_id": { "type": [ "string", "null" ], "format": "uuid" }, "properties": { "type": "object", "description": "Flat event properties object.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "whatsapp_config": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "business_phone_number": { "type": [ "string", "null" ] }, "meta_phone_number_id": { "type": [ "string", "null" ] } } }, "source_workflow": { "type": [ "object", "null" ], "properties": { "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "execution_id": { "type": [ "string", "null" ], "format": "uuid" }, "snapshot_id": { "type": [ "string", "null" ], "format": "uuid" }, "snapshot_version": { "type": [ "integer", "null" ] }, "test_mode": { "type": [ "boolean", "null" ] } } } } }, "FindingEvidenceCoOccurringEvent": { "type": "object", "required": [ "name", "event_count" ], "properties": { "name": { "type": "string" }, "event_count": { "type": "integer" }, "observed_at": { "type": "string", "format": "date-time", "description": "Only present on retry deltas." } } }, "FindingEvidenceDeltaItem": { "type": "object", "description": "One piece of evidence recorded after the previous investigation ran.", "required": [ "id", "observed_at", "source_type", "new_since_previous" ], "properties": { "id": { "type": "string", "format": "uuid" }, "observed_at": { "type": "string", "format": "date-time" }, "source_type": { "type": "string", "enum": [ "project_event", "conversation" ] }, "new_since_previous": { "type": "boolean" } } }, "FindingEvidenceSummary": { "type": "object", "required": [ "cutoff", "new_item_count" ], "properties": { "cutoff": { "type": [ "string", "null" ], "format": "date-time", "description": "Evidence recorded at or before this time was already investigated." }, "new_item_count": { "type": "integer" } } }, "FindingEvidenceCoverage": { "type": "object", "description": "How much of the underlying evidence this response contains.", "required": [ "source_event_count", "source_events_returned", "affected_conversations_returned", "comparison_conversations_returned", "source_event_limit", "affected_conversation_limit", "comparison_conversation_limit", "note" ], "properties": { "source_event_count": { "type": "integer" }, "source_events_returned": { "type": "integer" }, "affected_conversations_returned": { "type": "integer" }, "comparison_conversations_returned": { "type": "integer" }, "source_event_limit": { "type": "integer" }, "affected_conversation_limit": { "type": "integer" }, "comparison_conversation_limit": { "type": "integer" }, "note": { "type": [ "string", "null" ] }, "cutoff": { "type": [ "string", "null" ], "format": "date-time", "description": "Only present on retry deltas. Evidence recorded at or before this time was already\ncovered by the previous investigation.\n" }, "freshness": { "type": "string", "description": "Only present on retry deltas. How the cutoff is applied per source type." } } }, "FindingEvidenceGroup": { "type": "object", "description": "Evidence for one finding grouped with the requested one.", "required": [ "finding", "event_definition", "daily_history", "source_events", "affected_conversation_ids", "co_occurring_events" ], "properties": { "finding": { "$ref": "#/components/schemas/FindingEvidenceFinding" }, "event_definition": { "oneOf": [ { "$ref": "#/components/schemas/FindingEvidenceEventDefinition" }, { "type": "null" } ] }, "daily_history": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceDailyHistoryEntry" } }, "source_events": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceSourceEvent" } }, "affected_conversation_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "co_occurring_events": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceCoOccurringEvent" } }, "new_evidence": { "type": "array", "description": "Only present on retry deltas.", "items": { "$ref": "#/components/schemas/FindingEvidenceDeltaItem" } }, "historical_context": { "type": "array", "description": "Only present on retry deltas. Currently always empty.", "items": {} }, "evidence_summary": { "$ref": "#/components/schemas/FindingEvidenceSummary" } } }, "FindingEvidence": { "type": "object", "required": [ "finding", "event_definition", "coverage", "workflow", "daily_history", "source_events", "affected_conversation_ids", "comparison_conversation_ids", "co_occurring_events", "grouped_findings", "evidence_by_finding" ], "properties": { "finding": { "$ref": "#/components/schemas/FindingEvidenceFinding" }, "event_definition": { "oneOf": [ { "$ref": "#/components/schemas/FindingEvidenceEventDefinition" }, { "type": "null" } ] }, "coverage": { "$ref": "#/components/schemas/FindingEvidenceCoverage" }, "workflow": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "daily_history": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceDailyHistoryEntry" } }, "source_events": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceSourceEvent" } }, "affected_conversation_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "comparison_conversation_ids": { "type": "array", "description": "Conversations without the signal, for comparison.", "items": { "type": "string", "format": "uuid" } }, "co_occurring_events": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceCoOccurringEvent" } }, "grouped_findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceFinding" } }, "evidence_by_finding": { "type": "array", "items": { "$ref": "#/components/schemas/FindingEvidenceGroup" } }, "new_evidence": { "type": "array", "description": "Only present on retry deltas.", "items": { "$ref": "#/components/schemas/FindingEvidenceDeltaItem" } }, "historical_context": { "type": "array", "description": "Only present on retry deltas. Currently always empty.", "items": {} }, "evidence_summary": { "$ref": "#/components/schemas/FindingEvidenceSummary" } } }, "FindingEvidenceUnavailable": { "type": "object", "description": "Returned with `200` when evidence cannot be read for this finding's source.\nTell it apart from `FindingEvidence` by the presence of `error`.\n", "required": [ "error", "source_type", "source_key" ], "properties": { "error": { "type": "string" }, "source_type": { "type": [ "string", "null" ] }, "source_key": { "type": [ "string", "null" ] } } }, "FindingEvidenceResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/FindingEvidence" }, { "$ref": "#/components/schemas/FindingEvidenceUnavailable" } ] } } }, "FindingInvestigationAcceptedResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "finding_id", "investigation_id", "status" ], "properties": { "finding_id": { "type": "string", "format": "uuid" }, "investigation_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "investigating", "completed", "failed", "timed_out" ] } } } } }, "FindingVerificationMutationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "finding_id", "verification_id", "status" ], "properties": { "finding_id": { "type": "string", "format": "uuid" }, "verification_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "monitoring", "resolved", "not_improved", "dismissed" ] } } } } }, "WhatsappContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique contact ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "wa_id": { "type": [ "string", "null" ], "description": "WhatsApp ID (E.164 phone number). Can be null when Meta only provides BSUID-based identity.", "example": "15551234567" }, "business_scoped_user_id": { "type": [ "string", "null" ], "description": "WhatsApp business-scoped user ID", "example": "US.13491208655302741918" }, "parent_business_scoped_user_id": { "type": [ "string", "null" ], "description": "Parent business-scoped user ID when provided by Meta", "example": "US.ENT.506847293015824" }, "username": { "type": [ "string", "null" ], "description": "WhatsApp username when available", "example": "@testusername" }, "profile_name": { "type": "string", "description": "Name as shown on WhatsApp", "example": "John Doe" }, "display_name": { "type": "string", "nullable": true, "description": "Custom display name set by your app", "example": "John (VIP)" }, "customer_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Associated customer ID" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Custom key-value data" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WhatsappContactResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappContact" } } }, "WhatsappContactListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappContact" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "WhatsappContactMarketingPreference": { "type": "object", "description": "A contact's marketing message preference on one of your WhatsApp numbers. Recorded when the contact stops or resumes marketing messages inside WhatsApp. Read-only — only the contact can change it.", "properties": { "id": { "type": "string", "description": "Meta phone number ID of the number the preference applies to", "example": "123456789012345" }, "phone_number_id": { "type": "string", "description": "Meta phone number ID (same as `id`)", "example": "123456789012345" }, "status": { "type": "string", "enum": [ "stopped", "resumed" ], "description": "Current preference. `stopped` blocks marketing template sends to this contact on this number." }, "detail": { "type": [ "string", "null" ], "description": "Free-text reason reported by Meta", "example": "User requested to stop marketing messages" }, "source": { "type": "string", "description": "How the preference was captured. `meta_webhook` is Meta's `user_preferences` webhook; `meta_delivery_error` and `meta_synchronous_error` mean the stop was derived from a Meta `131050` send failure.", "enum": [ "meta_webhook", "meta_delivery_error", "meta_synchronous_error" ], "example": "meta_webhook" }, "marketing_allowed": { "type": "boolean", "description": "Whether marketing template sends are allowed. `false` when `status` is `stopped`." }, "config_display_name": { "type": [ "string", "null" ], "description": "Display name of the WhatsApp number" }, "last_event_at": { "type": "string", "format": "date-time", "description": "Timestamp WhatsApp reported for the latest preference change" }, "whatsapp_contact_id": { "type": "string", "format": "uuid" }, "internal_id": { "type": "string", "format": "uuid", "description": "Internal ID of the preference record" }, "whatsapp_config_id": { "type": "string", "format": "uuid", "description": "Internal ID of the WhatsApp number's configuration" }, "whatsapp_config_internal_id": { "type": "string", "format": "uuid", "description": "Same as `whatsapp_config_id`" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WhatsappContactMarketingPreferenceResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappContactMarketingPreference" } } }, "WhatsappContactMarketingPreferenceListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappContactMarketingPreference" } } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "InboxEmbed": { "type": "object", "required": [ "id", "scope_type", "status", "allowed_origins", "default_mode", "language", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "scope_type": { "type": "string", "description": "Public embed scope", "enum": [ "project", "customer", "phone_number" ] }, "scope_id": { "type": [ "string", "null" ], "description": "Customer UUID for `customer`, WhatsApp `phone_number_id` for `phone_number`, null for `project`" }, "scope_name": { "type": [ "string", "null" ], "description": "Human-readable customer or phone number label when available" }, "assigned_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Limits visible conversations to the active assignee" }, "assigned_user_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "allowed_origins": { "type": "array", "description": "Origins allowed to embed the inbox. Empty means any origin.", "items": { "type": "string" }, "example": [ "https://app.example.com" ] }, "default_mode": { "type": "string", "enum": [ "system", "light", "dark" ] }, "language": { "type": "string", "enum": [ "en", "es" ], "description": "UI language for the embedded inbox.", "default": "en" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "InboxEmbedCreated": { "allOf": [ { "$ref": "#/components/schemas/InboxEmbed" }, { "type": "object", "required": [ "token", "embed_url" ], "properties": { "token": { "type": "string", "description": "Raw inbox token. Returned only when the embed is created." }, "embed_url": { "type": "string", "format": "uri", "description": "Iframe URL. Returned only when the embed is created." } } } ] }, "InboxEmbedCreateRequest": { "type": "object", "required": [ "inbox_embed" ], "properties": { "inbox_embed": { "type": "object", "required": [ "scope_type" ], "properties": { "name": { "type": [ "string", "null" ] }, "scope_type": { "type": "string", "enum": [ "project", "customer", "phone_number" ] }, "scope_id": { "type": [ "string", "null" ], "description": "Required for `customer` and `phone_number`; must be blank for `project`" }, "assigned_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "default_mode": { "type": "string", "enum": [ "system", "light", "dark" ], "default": "system" }, "language": { "type": "string", "enum": [ "en", "es" ], "description": "UI language for the embedded inbox.", "default": "en" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "InboxEmbedUpdateRequest": { "type": "object", "required": [ "inbox_embed" ], "properties": { "inbox_embed": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "assigned_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "default_mode": { "type": "string", "enum": [ "system", "light", "dark" ] }, "language": { "type": "string", "enum": [ "en", "es" ], "description": "UI language for the embedded inbox." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "InboxEmbedResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InboxEmbed" } } }, "InboxEmbedCreatedResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InboxEmbedCreated" } } }, "InboxEmbedListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxEmbed" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginationMeta": { "type": "object", "required": [ "page", "per_page", "total_pages", "total_count" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1 }, "total_pages": { "type": "integer", "minimum": 0 }, "total_count": { "type": "integer", "minimum": 0 } } }, "PaginationCursor": { "type": "object", "properties": { "before": { "type": "string", "description": "Cursor for previous page (Base64 encoded)" }, "after": { "type": "string", "description": "Cursor for next page (Base64 encoded)" } } }, "Paging": { "type": "object", "properties": { "cursors": { "$ref": "#/components/schemas/PaginationCursor" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true } } }, "Customer": { "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "external_customer_id": { "type": [ "string", "null" ], "description": "Your internal customer ID" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CustomerCreateRequest": { "type": "object", "required": [ "customer" ], "properties": { "customer": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "external_customer_id": { "type": [ "string", "null" ] } } } } }, "CustomerUpdateRequest": { "type": "object", "required": [ "customer" ], "properties": { "customer": { "type": "object", "properties": { "name": { "type": "string" }, "external_customer_id": { "type": [ "string", "null" ] } } } } }, "CustomerResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } } }, "CustomerListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PhoneNumberReference": { "type": "object", "required": [ "id", "phone_number", "status", "country_iso", "country_dial_code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number": { "type": "string" }, "status": { "type": "string" }, "area_code": { "type": [ "string", "null" ] }, "country_iso": { "type": "string" }, "country_dial_code": { "type": "string" }, "display_number": { "type": [ "string", "null" ] } } }, "SetupLink": { "type": "object", "required": [ "id", "status", "created_at", "url", "meta_billing_mode" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "used", "expired", "revoked" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expires 30 days after creation by default" }, "url": { "type": "string", "format": "uri" }, "success_redirect_url": { "type": [ "string", "null" ], "format": "uri" }, "failure_redirect_url": { "type": [ "string", "null" ], "format": "uri" }, "allowed_origins": { "type": "array", "description": "HTTPS browser origins allowed to use this setup link with `@kapso/sdk`.", "items": { "type": "string", "format": "uri" } }, "allowed_connection_types": { "type": "array", "description": "`coexistence` - Use with WhatsApp Business App (5 msg/sec)\n`dedicated` - API-only through Kapso (up to 1000 msg/sec)\n\nProvide one value to auto-select for customer\n", "items": { "type": "string", "enum": [ "coexistence", "dedicated" ] }, "default": [ "coexistence", "dedicated" ] }, "meta_billing_mode": { "type": "string", "description": "Policy selected when the setup link was created.\n\n`customer_managed` uses the WABA's Meta payment method. `partner_managed` requests Kapso billing for the entire WABA after Meta returns the connected account. A custom Tech Provider app requires an active Kapso Multi-partner Solution.\n", "enum": [ "customer_managed", "partner_managed" ], "default": "customer_managed" }, "theme_config": { "type": [ "object", "null" ], "description": "Hex colors for hosted onboarding page", "properties": { "primary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Primary action buttons (default" }, "primary_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Text on primary buttons (default" }, "background_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Page background (default" }, "text_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Body text (default" }, "muted_text_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Secondary text (default" }, "card_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Card backgrounds (defaults to background_color)" }, "muted_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Disabled elements (default" }, "border_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Borders and dividers (default" }, "secondary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Secondary buttons (default" }, "secondary_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Text on secondary buttons (default" }, "destructive_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Error/danger buttons (default" }, "destructive_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Text on destructive buttons (default" } } }, "provision_phone_number": { "type": [ "boolean", "null" ], "description": "Auto-provision number during onboarding" }, "phone_number_area_code": { "type": [ "string", "null" ], "description": "US area code for provisioned numbers" }, "phone_number_country_isos": { "type": "array", "description": "Allowed countries for provisioning (defaults to [\"US\"])", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "reconnect_phone_number": { "type": [ "string", "null" ], "description": "Normalized E.164 digits of the customer's existing WhatsApp number this link is targeting for reconnect.\n\nSet this on create to scope the setup flow to a specific existing WhatsApp config for the same customer (token refresh / re-auth). When present, `provision_phone_number` is forced to `false` and `allowed_connection_types` is locked to match the existing config (`[\"dedicated\"]` or `[\"coexistence\"]`).\n" }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code for setup link UI (en, es, pt, hi, id, ar). Defaults to user's browser language.", "enum": [ "en", "es", "pt", "hi", "id", "ar", null ] }, "whatsapp_setup_status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "whatsapp_setup_error": { "type": [ "string", "null" ] }, "provisioned_phone_number": { "allOf": [ { "$ref": "#/components/schemas/PhoneNumberReference" } ] } } }, "SetupLinkCreateRequest": { "type": "object", "required": [ "setup_link" ], "properties": { "setup_link": { "type": "object", "properties": { "success_redirect_url": { "type": [ "string", "null" ], "format": "uri" }, "failure_redirect_url": { "type": [ "string", "null" ], "format": "uri" }, "allowed_origins": { "type": "array", "description": "HTTPS browser origins allowed to use the setup token with `@kapso/sdk`.", "items": { "type": "string", "format": "uri" } }, "provision_phone_number": { "type": "boolean", "description": "Requires your own telephony credentials on the project for non-US numbers" }, "phone_number_area_code": { "type": [ "string", "null" ], "description": "US only" }, "allowed_connection_types": { "type": "array", "description": "Single value auto-selects for customer", "items": { "type": "string", "enum": [ "coexistence", "dedicated" ] } }, "meta_billing_mode": { "type": "string", "description": "Meta billing policy for the WABA. This value cannot be changed after the link is created.\n\n`partner_managed` works with Kapso's default Meta app or a Tech Provider app covered by an active Kapso Multi-partner Solution. Final WABA eligibility is checked after connection; setup can complete even when billing attachment needs attention.\n", "enum": [ "customer_managed", "partner_managed" ], "default": "customer_managed" }, "theme_config": { "type": [ "object", "null" ], "properties": { "primary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "primary_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "background_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "text_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "muted_text_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "card_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "muted_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "border_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "secondary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "secondary_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "destructive_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "destructive_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } } }, "phone_number_country_isos": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "reconnect_phone_number": { "type": [ "string", "null" ], "description": "Existing WhatsApp number for this customer to reconnect. Phone numbers are normalized to E.164 digits.\n\nWhen set:\n- The number must match an existing production WhatsApp config on the customer\n- `provision_phone_number` must be `false` (or omitted)\n- `allowed_connection_types` must match the existing config (`[\"dedicated\"]` or `[\"coexistence\"]`)\n" }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code for setup link UI", "enum": [ "en", "es", "pt", "hi", "id", "ar", null ] } } } } }, "SetupLinkUpdateRequest": { "type": "object", "required": [ "setup_link" ], "properties": { "setup_link": { "type": "object", "properties": { "success_redirect_url": { "type": [ "string", "null" ], "format": "uri" }, "failure_redirect_url": { "type": [ "string", "null" ], "format": "uri" }, "allowed_origins": { "type": "array", "description": "HTTPS browser origins allowed to use the setup token with `@kapso/sdk`.", "items": { "type": "string", "format": "uri" } }, "provision_phone_number": { "type": "boolean" }, "phone_number_area_code": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "used", "expired", "revoked" ], "description": "Cannot change to `used`" }, "allowed_connection_types": { "type": "array", "items": { "type": "string", "enum": [ "coexistence", "dedicated" ] } }, "theme_config": { "type": [ "object", "null" ], "properties": { "primary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "primary_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "background_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "text_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "muted_text_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "card_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "muted_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "border_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "secondary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "secondary_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "destructive_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "destructive_foreground_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } } }, "phone_number_country_isos": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code for setup link UI", "enum": [ "en", "es", "pt", "hi", "id", "ar", null ] } } } } }, "SetupLinkResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SetupLink" } } }, "SetupLinkCreated": { "allOf": [ { "$ref": "#/components/schemas/SetupLink" }, { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "Opaque browser token returned only when the setup link is created. Pass it to `@kapso/sdk`; never expose your Kapso API key." } } } ] }, "SetupLinkCreateResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SetupLinkCreated" } } }, "SetupLinkListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SetupLink" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WhatsappPhoneNumber": { "type": "object", "required": [ "id", "internal_id", "phone_number_id", "name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Meta phone number ID" }, "internal_id": { "type": "string", "format": "uuid", "description": "Kapso configuration ID" }, "phone_number_id": { "type": "string", "description": "Meta phone number ID" }, "name": { "type": "string", "description": "Label for this number" }, "business_account_id": { "type": [ "string", "null" ], "description": "WhatsApp Business Account ID" }, "is_coexistence": { "type": [ "boolean", "null" ], "description": "Using with WhatsApp Business App" }, "inbound_processing_enabled": { "type": "boolean", "description": "Process incoming messages" }, "calls_enabled": { "type": "boolean", "description": "Handle voice calls" }, "webhook_verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Meta confirmed webhook" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ], "description": "Customer-facing display name" }, "display_phone_number": { "type": [ "string", "null" ], "description": "Formatted number from Meta" }, "display_phone_number_normalized": { "type": [ "string", "null" ], "description": "Digits only" }, "verified_name": { "type": [ "string", "null" ], "description": "Meta-verified business name" }, "quality_rating": { "type": [ "string", "null" ], "description": "GREEN, YELLOW, or RED" }, "code_verification_status": { "type": [ "string", "null" ] }, "name_status": { "type": [ "string", "null" ], "description": "Display name review status" }, "status": { "type": [ "string", "null" ], "description": "Connection status (e.g., CONNECTED)" }, "throughput_tier": { "type": [ "string", "null" ], "description": "Message rate limit tier" }, "whatsapp_business_manager_messaging_limit": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ] }, "is_official_business_account": { "type": [ "boolean", "null" ], "description": "Green checkmark verified" }, "is_pin_enabled": { "type": [ "boolean", "null" ], "description": "Two-factor PIN enabled" } } }, "WhatsappPhoneNumberCreateRequest": { "type": "object", "required": [ "whatsapp_phone_number" ], "properties": { "whatsapp_phone_number": { "type": "object", "required": [ "name", "phone_number_id", "business_account_id", "access_token" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "production", "sandbox" ], "default": "production", "description": "Production uses Meta credentials, sandbox uses test data" }, "phone_number_id": { "type": "string", "description": "From Meta" }, "business_account_id": { "type": "string", "description": "From Meta" }, "access_token": { "type": "string", "description": "Permanent token from Meta" }, "webhook_verify_token": { "type": [ "string", "null" ] }, "webhook_destination_url": { "type": [ "string", "null" ], "format": "uri", "description": "Your HTTPS endpoint for webhooks" }, "inbound_processing_enabled": { "type": "boolean", "default": true }, "calls_enabled": { "type": "boolean", "default": false } } } } }, "WhatsappPhoneNumberUpdateRequest": { "type": "object", "required": [ "whatsapp_phone_number" ], "properties": { "whatsapp_phone_number": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "production", "sandbox" ] }, "phone_number_id": { "type": "string", "description": "Required when switching to production" }, "business_account_id": { "type": "string" }, "access_token": { "type": "string" }, "webhook_verify_token": { "type": [ "string", "null" ] }, "webhook_destination_url": { "type": [ "string", "null" ], "format": "uri" }, "inbound_processing_enabled": { "type": "boolean" }, "calls_enabled": { "type": "boolean" } } } } }, "WhatsappPhoneNumberResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappPhoneNumber" } } }, "WhatsappPhoneNumberListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappPhoneNumber" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WhatsappPhoneNumberHealthResponse": { "type": "object", "required": [ "status", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded", "unhealthy", "error" ] }, "timestamp": { "type": "string", "format": "date-time" }, "retry_after": { "type": "string", "format": "date-time", "description": "Present only while the number is in access-error backoff. The earliest\ntime a later request will re-check Meta. Requests made before this time\nreturn this same cached payload. It is not a scheduled re-check or a\nguarantee that the next check will succeed.\n" }, "error": { "type": [ "string", "null" ] }, "checks": { "type": [ "object", "null" ], "additionalProperties": { "type": "object", "properties": { "passed": { "type": [ "boolean", "null" ] }, "details": { "type": "object", "additionalProperties": true }, "error": { "type": "string" } } }, "description": "Individual check results. Typical checks:\n- phone_number_access: Meta API connectivity\n- phone_number_connection: Meta connection status (CONNECTED/DISCONNECTED/UNKNOWN). `passed` is `null` when the status is UNKNOWN\n- messaging_health: Send/receive capability (AVAILABLE/LIMITED/BLOCKED)\n- webhook_subscription: WABA app subscription status\n- webhook_verified: Webhook verification status\n- token_validity: Access token validity (coexistence only)\n" } } }, "WhatsappWebhook": { "type": "object", "required": [ "id", "url", "kind", "events", "active", "created_at", "updated_at", "project_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "description": "Webhook delivery endpoint" }, "kind": { "type": "string", "enum": [ "kapso", "meta" ], "default": "kapso", "description": "Webhook type - 'kapso' for event-based webhooks, 'meta' for raw Meta payload forwarding" }, "events": { "type": "array", "description": "Event subscriptions (required for 'kapso' webhooks, empty for 'meta')", "items": { "type": "string" } }, "active": { "type": "boolean", "description": "Pause deliveries without deleting" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "project_id": { "type": "string", "format": "uuid" }, "phone_number_id": { "type": [ "string", "null" ], "description": "Meta phone number ID" }, "secret_key": { "type": [ "string", "null" ], "description": "Secret for signing requests" }, "headers": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Custom request headers" }, "buffer_enabled": { "type": [ "boolean", "null" ], "description": "Batch messages before delivery" }, "buffer_window_seconds": { "type": [ "integer", "null" ], "description": "Seconds to wait before sending batch" }, "max_buffer_size": { "type": [ "integer", "null" ], "description": "Max messages per batch" }, "buffer_events": { "type": "array", "description": "Events to buffer", "items": { "type": "string" } }, "inactivity_minutes": { "type": [ "integer", "null" ], "description": "Trigger inactivity event after N minutes" }, "payload_version": { "type": [ "string", "null" ], "description": "Webhook payload format version (defaults to 'v2')" } } }, "WhatsappWebhookRequest": { "type": "object", "required": [ "whatsapp_webhook" ], "properties": { "whatsapp_webhook": { "type": "object", "required": [ "url", "secret_key" ], "oneOf": [ { "title": "Kapso webhook", "description": "Event-based delivery in Kapso's payload format. This is the shape you get when `kind` is omitted, and it needs at least one event.", "required": [ "events" ], "properties": { "kind": { "const": "kapso" }, "events": { "type": "array", "minItems": 1 } } }, { "title": "Meta webhook", "description": "Raw Meta forwarding. `kind` must be given explicitly, and any events you send are normalized to an empty list.", "required": [ "kind" ], "properties": { "kind": { "const": "meta" } } } ], "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook delivery endpoint" }, "kind": { "type": "string", "enum": [ "kapso", "meta" ], "default": "kapso", "description": "Webhook type - 'kapso' for event-based webhooks, 'meta' for raw Meta payload forwarding" }, "secret_key": { "type": "string", "minLength": 1, "description": "Secret for request verification. Required for every webhook, including 'meta' ones, and never generated for you" }, "active": { "type": "boolean", "description": "Enable deliveries" }, "buffer_enabled": { "type": "boolean", "description": "Batch messages before delivery (not supported for 'meta' webhooks)" }, "buffer_window_seconds": { "type": [ "integer", "null" ], "description": "Seconds to wait (1-60, default 5)" }, "max_buffer_size": { "type": [ "integer", "null" ], "description": "Max messages per batch (1-100)" }, "inactivity_minutes": { "type": [ "integer", "null" ], "description": "Minutes before inactivity event" }, "events": { "type": "array", "description": "Event subscriptions (e.g., whatsapp.message.received). Required and non-empty when kind is 'kapso' (the default). For 'meta' webhooks anything you send here is normalized to an empty list, since Meta decides what it sends", "items": { "type": "string" } }, "buffer_events": { "type": "array", "description": "Events to buffer (not supported for 'meta' webhooks)", "items": { "type": "string" } }, "headers": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Custom request headers" }, "payload_version": { "type": [ "string", "null" ], "description": "Webhook payload format version (defaults to 'v2', not applicable for 'meta' webhooks)" } } } } }, "WhatsappWebhookUpdateRequest": { "type": "object", "required": [ "whatsapp_webhook" ], "properties": { "whatsapp_webhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook delivery endpoint" }, "kind": { "type": "string", "enum": [ "kapso", "meta" ], "description": "Webhook type (cannot be changed after creation)" }, "secret_key": { "type": [ "string", "null" ], "description": "Secret for request verification" }, "active": { "type": "boolean", "description": "Enable deliveries" }, "buffer_enabled": { "type": "boolean", "description": "Batch messages before delivery (not supported for 'meta' webhooks)" }, "buffer_window_seconds": { "type": [ "integer", "null" ], "description": "Seconds to wait (1-60, default 5)" }, "max_buffer_size": { "type": [ "integer", "null" ], "description": "Max messages per batch (1-100)" }, "inactivity_minutes": { "type": [ "integer", "null" ], "description": "Minutes before inactivity event" }, "events": { "type": "array", "description": "Event subscriptions (e.g., whatsapp.message.received) - required for 'kapso' webhooks, empty for 'meta'", "items": { "type": "string" } }, "buffer_events": { "type": "array", "description": "Events to buffer (not supported for 'meta' webhooks)", "items": { "type": "string" } }, "headers": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Custom request headers" }, "payload_version": { "type": [ "string", "null" ], "description": "Webhook payload format version (defaults to 'v2')" } } } } }, "WhatsappProjectWebhookRequest": { "type": "object", "required": [ "whatsapp_webhook" ], "properties": { "whatsapp_webhook": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook delivery endpoint" }, "phone_number_id": { "type": "string", "description": "Optional Meta phone number ID. Omit for project-scoped webhooks (project events only). Required for message/conversation events and all meta webhooks." }, "kind": { "type": "string", "enum": [ "kapso", "meta" ], "default": "kapso", "description": "Webhook type:\n- **kapso**: Event-based webhooks with filtered events, buffering support, and Kapso payload format (default)\n- **meta**: Raw Meta webhook forwarding - receives the exact payload Meta sends. Requires phone_number_id.\n" }, "secret_key": { "type": [ "string", "null" ], "description": "Secret for request verification" }, "active": { "type": "boolean", "description": "Enable deliveries" }, "buffer_enabled": { "type": "boolean", "description": "Batch messages before delivery (not supported for 'meta' webhooks)" }, "buffer_window_seconds": { "type": [ "integer", "null" ], "description": "Seconds to wait (1-60, default 5)" }, "max_buffer_size": { "type": [ "integer", "null" ], "description": "Max messages per batch (1-100)" }, "inactivity_minutes": { "type": [ "integer", "null" ], "description": "Minutes before inactivity event" }, "events": { "type": "array", "description": "Event subscriptions (project events for project-scoped webhooks, message/conversation events for number-scoped webhooks)", "items": { "type": "string" } }, "buffer_events": { "type": "array", "description": "Events to buffer (not supported for 'meta' webhooks)", "items": { "type": "string" } }, "headers": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Custom request headers" }, "payload_version": { "type": [ "string", "null" ], "description": "Webhook payload format version (defaults to 'v2')" } } } } }, "WhatsappWebhookResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappWebhook" } } }, "WhatsappWebhookListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappWebhook" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WhatsappBroadcastTemplate": { "type": "object", "required": [ "id", "name", "language_code", "category", "status" ], "properties": { "id": { "type": "string", "description": "Meta template ID when available, otherwise internal UUID for legacy support" }, "meta_template_id": { "type": [ "string", "null" ], "description": "Meta's external template identifier" }, "name": { "type": "string" }, "language_code": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "quality_score": { "type": [ "string", "null" ], "enum": [ "GREEN", "YELLOW", "RED", "UNKNOWN", null ], "description": "Meta's quality score for the template as of the last template sync or quality webhook. `UNKNOWN` means Meta reports the quality as unknown. `null` means Kapso has not received a score for this template yet. This is the template's current score, not the score at the time the broadcast was sent." }, "components": { "type": "array", "description": "Template component definitions (BODY, HEADER, BUTTON, etc.)", "items": { "type": "object", "additionalProperties": true } } } }, "WhatsappBroadcast": { "type": "object", "required": [ "id", "name", "status", "created_at", "updated_at", "total_recipients" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Campaign label" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "copying", "sending", "stopped", "completed", "failed" ], "description": "`copying` means the broadcast was duplicated from another one and its recipients are still being copied. Recipients cannot be added or cleared and the broadcast cannot be sent or scheduled until it becomes `draft`." }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When broadcast is scheduled to send" }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When sending started" }, "stopped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When sending was stopped" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When completed" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "sent_count": { "type": "integer", "minimum": 0, "description": "Messages sent" }, "failed_count": { "type": "integer", "minimum": 0, "description": "Failures" }, "delivered_count": { "type": "integer", "minimum": 0, "description": "Delivered" }, "read_count": { "type": "integer", "minimum": 0, "description": "Read" }, "pending_count": { "type": "integer", "minimum": 0, "description": "Pending" }, "suppressed_count": { "type": "integer", "minimum": 0, "description": "Recipients skipped because they stopped marketing messages on this number. Not sent, not charged, and excluded from sent_count and failed_count." }, "responded_count": { "type": "integer", "minimum": 0, "description": "Responses" }, "response_rate": { "type": "number", "format": "float", "description": "Response rate %" }, "total_recipients": { "type": "integer", "minimum": 0, "description": "Total recipients" }, "phone_number_id": { "type": [ "string", "null" ], "description": "Phone number ID" }, "whatsapp_template": { "anyOf": [ { "$ref": "#/components/schemas/WhatsappBroadcastTemplate" }, { "type": "null" } ] } } }, "WhatsappBroadcastCreateRequest": { "type": "object", "required": [ "whatsapp_broadcast" ], "properties": { "whatsapp_broadcast": { "type": "object", "required": [ "name", "phone_number_id", "whatsapp_template_id" ], "properties": { "name": { "type": "string", "description": "Campaign name" }, "phone_number_id": { "type": "string", "description": "Phone number ID to send from" }, "whatsapp_template_id": { "type": "string", "description": "Meta template ID (preferred) or internal UUID (legacy compatibility only). Migrate to Meta IDs for future compatibility." } } } } }, "WhatsappBroadcastResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappBroadcast" } } }, "WhatsappBroadcastUpdateRequest": { "type": "object", "required": [ "whatsapp_broadcast" ], "properties": { "whatsapp_broadcast": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "draft", "stopped" ], "description": "Set to `stopped` to stop a sending broadcast, or `draft` to cancel a scheduled broadcast." } } } } }, "WhatsappBroadcastListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappBroadcast" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WhatsappBroadcastRecipient": { "type": "object", "required": [ "id", "phone_number", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number": { "type": "string", "description": "E.164 format, no plus" }, "status": { "type": "string", "enum": [ "pending", "sent", "failed", "suppressed" ], "description": "Delivery status. `suppressed` means the contact stopped marketing messages on this number — nothing was sent and nothing was charged." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "read_at": { "type": [ "string", "null" ], "format": "date-time" }, "responded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "template_components": { "type": "array", "description": "Meta-style template components", "items": { "type": "object", "additionalProperties": true } }, "error_details": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Meta error payload. When Meta rejects the send, it holds `code`, `message`, `details`, `http_status`, and `fbtrace_id` from Meta's error, alongside `error_class`. Keys Meta did not return are omitted. For `suppressed` recipients it holds `code: marketing_preference_stopped` and a `detail` string instead." } } }, "WhatsappBroadcastRecipientListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappBroadcastRecipient" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WhatsappBroadcastRecipientsAddRequest": { "type": "object", "required": [ "whatsapp_broadcast" ], "properties": { "whatsapp_broadcast": { "type": "object", "required": [ "recipients" ], "properties": { "recipients": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "phone_number": { "type": "string", "description": "E.164 phone (required unless whatsapp_contact_id provided)" }, "whatsapp_contact_id": { "type": "string", "format": "uuid", "description": "Existing contact ID" }, "components": { "type": "array", "description": "Meta template components (body, header, button)", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "header", "body", "button" ] }, "sub_type": { "type": "string", "description": "Button sub_type (url, quick_reply)" }, "index": { "type": "integer", "description": "Button index (0-based)" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Parameter type (text, image, video, document)" }, "parameter_name": { "type": "string", "description": "Named parameter from template (e.g., first_name, discount_code)" }, "text": { "type": "string", "description": "Text value for text parameters" }, "image": { "type": "object", "description": "Image object for header images", "additionalProperties": true }, "video": { "type": "object", "description": "Video object for header videos", "additionalProperties": true }, "document": { "type": "object", "description": "Document object for header documents", "additionalProperties": true } }, "additionalProperties": true } } } } } } } } } } } }, "WhatsappBroadcastRecipientsAddResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "added", "duplicates", "errors" ], "properties": { "added": { "type": "integer", "minimum": 0 }, "duplicates": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "string" } } } } } }, "WhatsappBroadcastSendResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "stopped_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "WhatsappConversation": { "type": "object", "required": [ "id", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number": { "type": [ "string", "null" ], "description": "Contact's WhatsApp number. Can be null for BSUID-only identity." }, "business_scoped_user_id": { "type": [ "string", "null" ], "description": "WhatsApp business-scoped user ID" }, "parent_business_scoped_user_id": { "type": [ "string", "null" ], "description": "Parent business-scoped user ID when provided by Meta" }, "username": { "type": [ "string", "null" ], "description": "WhatsApp username when available" }, "status": { "type": "string", "enum": [ "active", "ended" ] }, "last_active_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "default": {}, "additionalProperties": true }, "phone_number_id": { "type": [ "string", "null" ] }, "kapso": { "type": [ "object", "null" ], "description": "Conversation metadata", "properties": { "contact_name": { "type": [ "string", "null" ] }, "messages_count": { "type": "integer", "minimum": 0 }, "last_message_id": { "type": [ "string", "null" ] }, "last_message_type": { "type": [ "string", "null" ] }, "last_message_timestamp": { "type": "string", "format": "date-time" }, "last_message_text": { "type": [ "string", "null" ] }, "last_inbound_at": { "type": "string", "format": "date-time" }, "last_outbound_at": { "type": "string", "format": "date-time" } } } } }, "WhatsappConversationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappConversation" } } }, "WhatsappConversationUpdateRequest": { "type": "object", "required": [ "whatsapp_conversation" ], "properties": { "whatsapp_conversation": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "ended" ] } } } } }, "ConversationAssignment": { "type": "object", "required": [ "id", "user_id", "active", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid", "description": "ID of the user assigned to the conversation" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the user who created the assignment" }, "notes": { "type": [ "string", "null" ], "description": "Optional notes about the assignment" }, "active": { "type": "boolean", "description": "Whether this assignment is currently active" }, "created_at": { "type": "string", "format": "date-time" } } }, "ConversationAssignmentResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ConversationAssignment" } } }, "ConversationAssignmentListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationAssignment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "ConversationAssignmentCreateRequest": { "type": "object", "required": [ "assignment" ], "properties": { "assignment": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "format": "uuid", "description": "ID of the user to assign" }, "notes": { "type": "string", "description": "Optional notes about the assignment" } } } } }, "ConversationAssignmentUpdateRequest": { "type": "object", "required": [ "assignment" ], "properties": { "assignment": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "ID of the user to reassign to" }, "notes": { "type": "string", "description": "Updated notes" }, "active": { "type": "boolean", "description": "Set to false to unassign" } } } } }, "WhatsappConversationListResponse": { "type": "object", "required": [ "data", "paging" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappConversation" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "WhatsappMessage": { "type": "object", "description": "WhatsApp message in Meta-compatible format with Kapso extensions.\nThe structure mirrors Meta's webhook payload format.\n", "required": [ "id", "timestamp", "type", "kapso" ], "properties": { "id": { "type": "string", "description": "WhatsApp message ID (WAMID)", "example": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQUY5" }, "timestamp": { "type": "string", "description": "Unix timestamp in seconds (as string per Meta convention)", "example": "1705329600" }, "type": { "type": "string", "description": "Message type", "enum": [ "text", "image", "video", "audio", "document", "location", "interactive", "template", "reaction", "contacts", "sticker", "button", "order" ] }, "from": { "type": [ "string", "null" ], "description": "Sender phone number when phone-based identity is available", "example": "15551234567" }, "from_user_id": { "type": [ "string", "null" ], "description": "Sender business-scoped user ID when available", "example": "US.13491208655302741918" }, "from_parent_user_id": { "type": [ "string", "null" ], "description": "Sender parent business-scoped user ID when available", "example": "US.ENT.506847293015824" }, "to": { "type": [ "string", "null" ], "description": "Recipient phone number when phone-based identity is available", "example": "15551234567" }, "to_user_id": { "type": [ "string", "null" ], "description": "Recipient business-scoped user ID when available", "example": "US.13491208655302741918" }, "to_parent_user_id": { "type": [ "string", "null" ], "description": "Recipient parent business-scoped user ID when available", "example": "US.ENT.506847293015824" }, "username": { "type": [ "string", "null" ], "description": "WhatsApp username when available", "example": "@testusername" }, "context": { "type": "object", "description": "Reply context when message is a reply", "properties": { "id": { "type": "string", "description": "ID of the message being replied to" }, "from": { "type": "string", "description": "Phone number of original message sender" }, "referred_product": { "type": "object", "description": "Product being referenced", "additionalProperties": true } } }, "text": { "type": "object", "description": "Text message payload (when type=text)", "properties": { "body": { "type": "string" } } }, "image": { "type": "object", "description": "Image message payload (when type=image)", "properties": { "id": { "type": "string", "description": "Media ID from Meta" }, "link": { "type": "string", "format": "uri" }, "caption": { "type": "string" } } }, "video": { "type": "object", "description": "Video message payload (when type=video)", "properties": { "id": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "caption": { "type": "string" } } }, "audio": { "type": "object", "description": "Audio message payload (when type=audio)", "properties": { "id": { "type": "string" }, "link": { "type": "string", "format": "uri" } } }, "document": { "type": "object", "description": "Document message payload (when type=document)", "properties": { "id": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "caption": { "type": "string" } } }, "location": { "type": "object", "description": "Location message payload (when type=location)", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": "string" }, "address": { "type": "string" } } }, "sticker": { "type": "object", "description": "Sticker message payload (when type=sticker)", "properties": { "id": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "mime_type": { "type": "string" }, "animated": { "type": "boolean" } } }, "interactive": { "type": "object", "description": "Interactive message payload (when type=interactive)", "additionalProperties": true }, "button": { "type": "object", "description": "Button response payload (when type=button)", "properties": { "text": { "type": "string" }, "payload": { "type": "string" } } }, "template": { "type": "object", "description": "Template message payload (when type=template)", "properties": { "name": { "type": "string" }, "language": { "type": "object", "properties": { "code": { "type": "string" } } }, "components": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "reaction": { "type": "object", "description": "Reaction message payload (when type=reaction)", "properties": { "emoji": { "type": "string" }, "message_id": { "type": "string" } } }, "contacts": { "type": "array", "description": "Contacts message payload (when type=contacts)", "items": { "type": "object", "additionalProperties": true } }, "order": { "type": "object", "description": "Order message payload (when type=order)", "properties": { "catalog_id": { "type": "string" }, "product_items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "order_text": { "type": "string" } } }, "kapso": { "type": "object", "description": "Kapso-specific extensions", "required": [ "direction", "status", "whatsapp_conversation_id" ], "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "status": { "type": "string", "enum": [ "pending", "sent", "delivered", "read", "failed" ] }, "processing_status": { "type": "string", "enum": [ "pending", "processed", "blocked" ] }, "origin": { "type": "string", "description": "Message origin", "enum": [ "cloud_api", "business_app", "history_sync" ] }, "phone_number": { "type": [ "string", "null" ], "description": "Contact phone number" }, "phone_number_id": { "type": [ "string", "null" ], "description": "Meta phone number ID for the WhatsApp number" }, "has_media": { "type": "boolean" }, "whatsapp_conversation_id": { "type": "string", "format": "uuid", "description": "Kapso conversation ID" }, "contact_name": { "type": [ "string", "null" ], "description": "Contact name if available" }, "content": { "type": [ "string", "null" ], "description": "Text content of the message" }, "statuses": { "type": "array", "description": "Status event history (raw Meta payloads)", "items": { "type": "object", "additionalProperties": true } }, "transcript": { "type": "object", "description": "Audio transcript (for audio messages)", "properties": { "text": { "type": "string" } } }, "media_data": { "type": "object", "description": "Media attachment details", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "byte_size": { "type": "integer" } } }, "media_url": { "type": "string", "format": "uri", "description": "Direct media URL" }, "message_type_data": { "type": "object", "description": "Type-specific data (caption, template params, etc.)", "additionalProperties": true }, "flow_response": { "type": "object", "description": "WhatsApp Flow response data", "additionalProperties": true }, "flow_token": { "type": "string" }, "flow_name": { "type": "string" }, "order_text": { "type": "string", "description": "Order text for order messages" } } } } }, "WhatsappMessageResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappMessage" } } }, "WhatsappMessageListResponse": { "type": "object", "required": [ "data", "paging" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappMessage" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "MessageStatusEvent": { "type": "object", "description": "Raw Meta status event payload", "properties": { "id": { "type": "string", "description": "Message ID" }, "status": { "type": "string", "enum": [ "sent", "delivered", "read", "failed" ] }, "timestamp": { "type": "string", "description": "Unix timestamp" }, "recipient_id": { "type": "string" }, "conversation": { "type": "object", "properties": { "id": { "type": "string" }, "origin": { "type": "object", "properties": { "type": { "type": "string" } } }, "expiration_timestamp": { "type": "string" } } }, "pricing": { "type": "object", "properties": { "billable": { "type": "boolean" }, "pricing_model": { "type": "string" }, "category": { "type": "string" } } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "WhatsappDisplayNameRequest": { "type": "object", "required": [ "id", "requested_display_name", "status", "submitted_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number_id": { "type": [ "string", "null" ], "description": "Meta phone number ID" }, "requested_display_name": { "type": "string" }, "previous_display_name": { "type": [ "string", "null" ], "description": "Previous display name" }, "status": { "type": "string", "enum": [ "submitted", "pending_review", "approved", "available_without_review", "deferred", "declined", "expired", "no_review", "failed", "applied", "cancelled" ] }, "submitted_at": { "type": "string", "format": "date-time" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "meta_error_code": { "type": [ "integer", "null" ] }, "meta_error_subcode": { "type": [ "integer", "null" ] }, "meta_error_type": { "type": [ "string", "null" ] }, "meta_error_message": { "type": [ "string", "null" ] } } }, "WhatsappDisplayNameRequestCreate": { "type": "object", "required": [ "display_name_request" ], "properties": { "display_name_request": { "type": "object", "required": [ "new_display_name" ], "properties": { "new_display_name": { "type": "string", "description": "Display name to request (max 256 chars)" } } } } }, "WhatsappDisplayNameRequestResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappDisplayNameRequest" } } }, "WhatsappDisplayNameRequestListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappDisplayNameRequest" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "MediaIngest": { "type": "object", "required": [ "phone_number_id", "source" ], "properties": { "phone_number_id": { "type": "string", "description": "Meta phone number ID" }, "source": { "type": "string", "format": "uri", "description": "HTTP/HTTPS URL to media file" }, "delivery": { "type": "string", "enum": [ "meta_media", "meta_resumable_asset" ], "default": "meta_media", "description": "Upload method:\n- meta_media: Standard upload (30-day lifetime)\n- meta_resumable_asset: Resumable upload (profile pictures, etc.)\n" }, "filename": { "type": "string", "description": "Optional filename hint" }, "mime_type": { "type": "string", "description": "Optional MIME type hint" } } }, "MediaIngestRequest": { "type": "object", "required": [ "media_ingest" ], "properties": { "media_ingest": { "$ref": "#/components/schemas/MediaIngest" } } }, "MediaIngestTarget": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "meta_media", "meta_resumable_asset" ], "description": "Upload method used" }, "media_id": { "type": "string", "description": "Meta media ID (present when kind=meta_media)" }, "handle": { "type": "string", "description": "Resumable upload handle (present when kind=meta_resumable_asset)" } } }, "MediaIngestResource": { "type": "object", "required": [ "filename", "mime_type", "size_bytes", "sha256", "source_url" ], "properties": { "filename": { "type": "string", "description": "Detected or provided filename" }, "mime_type": { "type": "string", "description": "Detected or provided MIME type" }, "size_bytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "sha256": { "type": "string", "description": "SHA256 checksum" }, "source_url": { "type": "string", "format": "uri", "description": "Original source URL" } } }, "MediaIngestData": { "type": "object", "required": [ "ingest_id", "target", "resource" ], "properties": { "ingest_id": { "type": "string", "format": "uuid", "description": "Unique ingest request ID" }, "target": { "$ref": "#/components/schemas/MediaIngestTarget" }, "resource": { "$ref": "#/components/schemas/MediaIngestResource" } } }, "MediaIngestResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MediaIngestData" } } }, "User": { "type": "object", "required": [ "id", "user_id", "email", "name", "role" ], "properties": { "id": { "type": "integer", "description": "User project membership ID" }, "user_id": { "type": "string", "format": "uuid", "description": "User account ID" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "name": { "type": "string", "description": "User display name" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "User role in the project" } } }, "UsersResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "ProjectEvent": { "type": "object", "required": [ "id", "name", "occurred_at", "conversation_id", "properties" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event ID" }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$", "description": "Event name. Must be lowercase and may contain optional dot-separated segments. Maximum 128 characters.", "example": "conversation.csat_scored" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred" }, "conversation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Linked WhatsApp conversation ID, when provided" }, "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Flat event properties object" } } }, "ProjectEventCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$", "description": "Event name. Must be lowercase and may contain optional dot-separated segments. Each segment starts with a lowercase letter and may contain lowercase letters, numbers, and underscores. Maximum 128 characters.", "example": "conversation.csat_scored" }, "occurred_at": { "type": "string", "format": "date-time", "description": "Optional event timestamp. Defaults to the current time." }, "conversation_id": { "type": "string", "format": "uuid", "description": "Optional WhatsApp conversation ID to link to the event" }, "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Optional flat event properties object" } } }, "ProjectEventResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProjectEvent" } } }, "ProjectEventListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectEvent" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "ProjectEventDefinition": { "type": "object", "required": [ "id", "name", "property_schema", "created_at", "updated_at", "archived_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event definition ID" }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$", "description": "Event name. Must be lowercase and may contain optional dot-separated segments. Each segment starts with a lowercase letter and may contain lowercase letters, numbers, and underscores. Maximum 128 characters.", "example": "conversation.csat_scored" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what this event means" }, "property_schema": { "type": "object", "additionalProperties": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean" ] } } }, "description": "Declared properties for this event. Values are keyed by property name.", "example": { "score": { "type": "number" }, "reason": { "type": "string" } } }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the latest emitted event with this definition, when available." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the definition was archived, or null when active." } } }, "ProjectEventDefinitionCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$", "description": "Event name. Must be lowercase and may contain optional dot-separated segments. Each segment starts with a lowercase letter and may contain lowercase letters, numbers, and underscores. Maximum 128 characters.", "example": "conversation.csat_scored" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what this event means" }, "property_schema": { "type": "object", "additionalProperties": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean" ] } } }, "description": "Declared properties for this event. Values are keyed by property name.", "example": { "score": { "type": "number" }, "reason": { "type": "string" } } } } }, "ProjectEventDefinitionUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$", "description": "Event name. Must be lowercase and may contain optional dot-separated segments. Each segment starts with a lowercase letter and may contain lowercase letters, numbers, and underscores. Maximum 128 characters. Cannot be changed after events have been recorded.", "example": "conversation.csat_scored" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what this event means" }, "property_schema": { "type": "object", "additionalProperties": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean" ] } } }, "description": "Declared properties for this event. Values are keyed by property name." }, "archived": { "type": "boolean", "description": "Archive or restore the definition. Archived definitions retain historical events but are hidden from new tools and workflow selectors." } } }, "ProjectEventDefinitionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProjectEventDefinition" } } }, "ProjectEventDefinitionListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectEventDefinition" } } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "event", "status", "attempt_count", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "description": "The webhook event type" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP response status code from the webhook endpoint" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "attempt_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "webhook_id": { "type": [ "string", "null" ], "format": "uuid" }, "webhook_url": { "type": [ "string", "null" ] }, "whatsapp_config_id": { "type": [ "string", "null" ], "format": "uuid" }, "phone_number_id": { "type": [ "string", "null" ], "description": "Meta phone number ID" }, "conversation_phone_number": { "type": [ "string", "null" ], "description": "Phone number of the conversation associated with the delivery" } } }, "WebhookDeliveryListResponse": { "type": "object", "required": [ "data", "paging" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "ExternalApiLog": { "type": "object", "required": [ "id", "endpoint", "http_method", "response_status", "response_time_ms", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "endpoint": { "type": "string", "description": "The API endpoint that was called" }, "http_method": { "type": "string", "description": "HTTP method used (GET, POST, etc.)" }, "response_status": { "type": "integer", "description": "HTTP response status code" }, "response_time_ms": { "type": "number", "description": "Response time in milliseconds" }, "ip_address": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "api_key_name": { "type": [ "string", "null" ], "description": "Name of the API key used for the request" } } }, "ExternalApiLogListResponse": { "type": "object", "required": [ "data", "paging" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalApiLog" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "LogSearchEvent": { "type": "object", "additionalProperties": true, "required": [ "id", "source" ], "properties": { "id": { "type": "string", "description": "Indexed log event ID", "example": "evt_1" }, "source": { "type": "string", "enum": [ "external_api_log", "whatsapp_webhook_event", "flow_event", "webhook_delivery" ], "example": "external_api_log" }, "timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "ingested_at": { "type": [ "string", "null" ], "format": "date-time" }, "level": { "type": [ "string", "null" ], "example": "info" }, "status": { "type": [ "string", "null" ], "example": "failed" }, "message": { "type": [ "string", "null" ], "example": "POST /v1/messages" }, "resource_type": { "type": [ "string", "null" ], "example": "external_api_log" }, "resource_id": { "type": [ "string", "null" ] }, "http_method": { "type": [ "string", "null" ], "example": "POST" }, "endpoint": { "type": [ "string", "null" ], "example": "/v1/messages" }, "api_key_id": { "type": [ "string", "null" ] }, "api_key_name": { "type": [ "string", "null" ], "example": "Production key" }, "response_status": { "type": [ "integer", "null" ], "example": 422 }, "response_time_ms": { "type": [ "number", "null" ] }, "event_type": { "type": [ "string", "null" ], "example": "agent_iteration_started" }, "field": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "message_type": { "type": [ "string", "null" ] }, "phone_number_id": { "type": [ "string", "null" ] }, "display_phone_number": { "type": [ "string", "null" ] }, "flow_name": { "type": [ "string", "null" ], "example": "Support workflow" }, "flow_id": { "type": [ "string", "null" ] }, "flow_execution_id": { "type": [ "string", "null" ] }, "flow_event_id": { "type": [ "string", "null" ] }, "step_identifier": { "type": [ "string", "null" ], "example": "agent_1" }, "step_type": { "type": [ "string", "null" ] }, "webhook_id": { "type": [ "string", "null" ] }, "webhook_url": { "type": [ "string", "null" ] }, "error_class": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "attributes": { "type": [ "object", "null" ], "additionalProperties": true }, "payload": { "type": [ "object", "null" ], "additionalProperties": true } } }, "LogSearchWindow": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" } } }, "LogSearchPagination": { "type": "object", "properties": { "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": [ "string", "null" ] } } }, "LogSearchResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "available", "events" ], "properties": { "available": { "type": "boolean" }, "source": { "type": [ "string", "array", "null" ], "items": { "type": "string" } }, "window": { "$ref": "#/components/schemas/LogSearchWindow" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/LogSearchEvent" } }, "pagination": { "$ref": "#/components/schemas/LogSearchPagination" }, "error": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] } } } } }, "LogSearchFilterValue": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "LogSearchFilterEntry": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "example": "flow_execution_id" }, "value": { "$ref": "#/components/schemas/LogSearchFilterValue" } } }, "LogSearchRequest": { "type": "object", "properties": { "query": { "type": "string" }, "period": { "type": "string", "enum": [ "24h", "7d", "context" ], "default": "24h" }, "source": { "type": "string", "enum": [ "all", "external_api_log", "whatsapp_webhook_event", "flow_event", "webhook_delivery" ], "default": "all" }, "problems_only": { "type": "boolean", "default": false }, "errors_only": { "type": "boolean", "default": false, "deprecated": true, "description": "Alias for problems_only." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "cursor": { "type": "string", "description": "Cursor returned as pagination.next_cursor from a previous response." }, "around": { "type": "string", "format": "date-time", "description": "Center a context search around this timestamp. Use with period=context." }, "highlight_event_id": { "type": "string", "description": "Include this event in the page when available." }, "highlight_resource_id": { "type": "string", "description": "Include an event for this resource in the page when available." }, "filters": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LogSearchFilterValue" } }, { "type": "array", "items": { "$ref": "#/components/schemas/LogSearchFilterEntry" } } ], "example": { "flow_execution_id": "flow-execution-1" } } } }, "LogSearchCatalogResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "catalog": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } } } } }, "filter_suggestions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "param_key": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } } } } }, "detail_fields": { "type": "array", "items": { "type": "string" } } } } } } } }, "ProviderModel": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Model name" }, "provider": { "type": [ "string", "null" ], "description": "Provider name (e.g., OpenAI, Anthropic)" }, "reasoning_model": { "type": "boolean", "description": "Whether the model supports reasoning controls." }, "thinking_mode": { "type": "string", "description": "How extended thinking is applied for this model. `disabled` means no thinking, `manual` uses a fixed thinking budget, `adaptive` lets the model size its own thinking from the reasoning effort.", "enum": [ "disabled", "manual", "adaptive", "always_adaptive" ] }, "supports_custom_sampling": { "type": "boolean", "description": "Whether the model accepts custom sampling parameters such as temperature. Sampling parameters are ignored while extended thinking is active." }, "supported_reasoning_efforts": { "type": "array", "description": "Reasoning efforts accepted by this model. Empty for non-reasoning models.", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "default_reasoning_effort": { "type": [ "string", "null" ], "description": "Default reasoning effort to use when no effort is specified.", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max", null ] }, "supported_prompt_cache_ttls": { "type": "array", "description": "Prompt cache TTLs accepted by this model. Empty for models without prompt caching.", "items": { "type": "string", "enum": [ "5m", "1h" ] } }, "default_prompt_cache_ttl": { "type": [ "string", "null" ], "description": "Default prompt cache TTL. `null` for models without prompt caching.", "enum": [ "5m", "1h", null ] }, "api_surface": { "type": "string", "description": "API surface Kapso uses for the provider model.", "enum": [ "provider_default", "chat_completions", "responses" ] } } }, "ProviderModelListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderModel" } } } }, "ConfigurePropRequest": { "type": "object", "required": [ "prop_name" ], "properties": { "prop_name": { "type": "string", "description": "Name of the prop to configure" }, "configured_props": { "type": "object", "additionalProperties": true, "description": "Current prop values" }, "dynamic_props_id": { "type": "string", "description": "Dynamic props session ID" } } }, "ReloadPropsRequest": { "type": "object", "properties": { "configured_props": { "type": "object", "additionalProperties": true, "description": "Current prop values" }, "dynamic_props_id": { "type": "string", "description": "Dynamic props session ID" } } }, "ConfigurePropResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "DeleteSuccessResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } }, "WhatsappFlow": { "type": "object", "required": [ "id", "meta_flow_id", "name", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "meta_flow_id": { "type": "string", "description": "Meta's flow identifier" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "json_version": { "type": [ "string", "null" ], "description": "WhatsApp Flow JSON version" }, "data_api_version": { "type": [ "string", "null" ], "description": "Data API version for the flow" }, "business_account_id": { "type": [ "string", "null" ], "description": "WhatsApp Business Account ID" }, "preview_url": { "type": [ "string", "null" ], "format": "uri", "description": "Meta preview URL (draft flows only)" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "data_endpoint_function_id": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the associated data endpoint function" }, "phone_number_id": { "type": [ "string", "null" ], "description": "Meta phone number ID associated with this flow" }, "data_endpoint_url": { "type": [ "string", "null" ], "format": "uri", "description": "Data endpoint URL when configured" }, "has_data_endpoint": { "type": "boolean", "description": "Whether data endpoint is fully configured" }, "flows_encryption_configured": { "type": "boolean", "description": "Whether flows encryption is set up" } } }, "WhatsappFlowVersion": { "type": "object", "required": [ "id", "version_label", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version_label": { "type": "string", "description": "Version identifier" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "flow_json_sha": { "type": [ "string", "null" ], "description": "SHA256 hash of flow JSON" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "validation_errors": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true }, "description": "Meta validation errors" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WhatsappFlowVersionDetail": { "allOf": [ { "$ref": "#/components/schemas/WhatsappFlowVersion" }, { "type": "object", "properties": { "flow_json": { "type": "object", "additionalProperties": true, "description": "WhatsApp Flow JSON definition" } } } ] }, "WhatsappFlowDataEndpoint": { "type": "object", "required": [ "function_id", "function_name", "status" ], "properties": { "function_id": { "type": "string", "format": "uuid" }, "function_name": { "type": "string" }, "endpoint_url": { "type": [ "string", "null" ], "format": "uri" }, "status": { "type": "string", "enum": [ "draft", "deployed", "error" ] }, "last_deployed_at": { "type": [ "string", "null" ], "format": "date-time" }, "code": { "type": "string", "description": "Function source code" } } }, "WhatsappFlowCreateRequest": { "type": "object", "required": [ "phone_number_id" ], "properties": { "phone_number_id": { "type": "string", "description": "Meta phone number ID to use" }, "name": { "type": "string", "description": "Flow name (auto-generated if omitted)" }, "flow_json": { "type": "object", "additionalProperties": true, "description": "WhatsApp Flow JSON (defaults to a basic welcome screen)" }, "publish": { "type": "boolean", "default": false, "description": "Publish immediately after creation" } } }, "WhatsappFlowVersionCreateRequest": { "type": "object", "required": [ "flow_json" ], "properties": { "flow_json": { "type": "object", "additionalProperties": true, "description": "WhatsApp Flow JSON definition" }, "phone_number_id": { "type": "string", "description": "Override phone number (optional)" } } }, "WhatsappFlowDataEndpointCreateRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Cloudflare Worker code for the data endpoint" } } }, "WhatsappFlowDataEndpointAttachRequest": { "type": "object", "required": [ "function_id" ], "properties": { "function_id": { "type": "string", "format": "uuid", "description": "UUID of an existing deployed function in this project. Null or empty values are rejected." } } }, "WhatsappFlowResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappFlow" } } }, "WhatsappFlowListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappFlow" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WhatsappFlowVersionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappFlowVersion" } } }, "WhatsappFlowVersionDetailResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappFlowVersionDetail" } } }, "WhatsappFlowVersionListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappFlowVersion" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WhatsappFlowDataEndpointResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappFlowDataEndpoint" } } }, "WhatsappFlowDataEndpointRegisterResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WhatsappFlowDataEndpoint" }, { "type": "object", "properties": { "flow_id": { "type": "string", "format": "uuid" }, "flow_data_endpoint_function_id": { "type": "string", "format": "uuid" }, "flow_has_encryption": { "type": "boolean" }, "warning": { "type": [ "string", "null" ], "description": "The endpoint was updated but automatic republishing failed." } } } ] } } }, "WhatsappFlowDataEndpointAttachResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WhatsappFlowDataEndpoint" }, { "type": "object", "properties": { "flow_id": { "type": "string", "format": "uuid" }, "flow_data_endpoint_function_id": { "type": "string", "format": "uuid" }, "flow_has_encryption": { "type": "boolean" }, "warning": { "type": [ "string", "null" ], "description": "Set when the flow was published and could not be automatically republished after the change" } } } ] } } }, "WhatsappFlowFunctionLog": { "type": "object", "properties": { "level": { "type": "string" }, "message": { "type": "string" }, "logged_at": { "type": "string", "format": "date-time" }, "stack": { "type": [ "string", "null" ] }, "cf_ray": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] } } }, "WhatsappFlowFunctionLogsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "function_id", "function_name", "logs" ], "properties": { "function_id": { "type": "string", "format": "uuid" }, "function_name": { "type": "string" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappFlowFunctionLog" } } } } } }, "WhatsappFlowFunctionInvocation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status_code": { "type": "integer" }, "duration_ms": { "type": [ "number", "null" ] }, "request_body": { "type": [ "object", "null" ], "additionalProperties": true }, "response_body": { "type": [ "object", "null" ], "additionalProperties": true }, "error_message": { "type": [ "string", "null" ] }, "cf_ray": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "WhatsappFlowFunctionInvocationsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "function_id", "function_name", "invocations" ], "properties": { "function_id": { "type": "string", "format": "uuid" }, "function_name": { "type": "string" }, "invocations": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappFlowFunctionInvocation" } } } } } }, "WhatsappFlowEncryptionSetupResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "message", "flows_encryption_configured" ], "properties": { "status": { "type": "string", "enum": [ "success", "already_configured" ] }, "message": { "type": "string" }, "flows_encryption_configured": { "type": "boolean" } } } } }, "WhatsappFunding": { "type": "object", "required": [ "waba_id", "business_portfolio_id", "status", "reason", "message", "currency", "waba_currency", "last_verified_at", "last_checked_at", "paid_messages", "operation" ], "properties": { "waba_id": { "type": "string", "description": "Meta WhatsApp Business Account ID.", "example": "4188880514714289" }, "business_portfolio_id": { "type": "string", "nullable": true, "description": "Meta Business Portfolio ID that owns the WABA.", "example": "1991231921410797" }, "status": { "type": "string", "description": "Funding state derived from locally persisted evidence.\n\n- `funded`: funding is verified, the allocation is approved and observed funding IDs match.\n- `pending`: an initial funding operation is in progress.\n- `unknown`: previously verified, but current evidence cannot confirm funding.\n- `not_funded`: funding was never verified, including an attempt retired because the customer kept their existing Meta payment method.\n- `revoked`: Meta allocation evidence confirms the funding was deleted.\n", "enum": [ "funded", "pending", "unknown", "not_funded", "revoked" ] }, "reason": { "type": "string", "nullable": true, "description": "Machine-readable reason, `null` when `status` is `funded`. Treat as an extensible string; new values can be added.", "example": "existing_payment_method" }, "message": { "type": "string", "description": "Display copy for `reason`. Do not parse.", "example": "Existing Meta payment method kept." }, "currency": { "type": "string", "description": "Kapso settlement currency.", "example": "USD" }, "waba_currency": { "type": "string", "nullable": true, "description": "Funding snapshot currency, or the observed WABA currency when no funding attachment exists.", "example": "USD" }, "last_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest recorded transition into verified funding." }, "last_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last funding check, including failed attempts." }, "paid_messages": { "type": "object", "description": "Local billing pauses on this project's funding attachment. Not an authorization promise - balance, credentials and Meta restrictions can still block sending.", "required": [ "paused", "reasons" ], "properties": { "paused": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "operation": { "$ref": "#/components/schemas/WhatsappFundingRun" } } }, "WhatsappFundingRun": { "type": "object", "nullable": true, "description": "Latest funding run for this WABA in your project, or `null` when no run was ever started. A terminal run does not promise funding - read `status` on the funding object as well.", "required": [ "id", "status", "started_at", "finished_at", "error_kind", "meta_error_code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled", "expired" ] }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true }, "error_kind": { "type": "string", "nullable": true, "description": "Machine-readable failure class of the run. Treat as an extensible string. No provider messages or credentials are included." }, "meta_error_code": { "type": "integer", "nullable": true, "description": "Meta error code recorded for the failed run, when one was returned." } } }, "WhatsappEnsureFundingRequest": { "type": "object", "required": [ "business_portfolio_id" ], "properties": { "business_portfolio_id": { "type": "string", "description": "Meta Business Portfolio ID that owns the WABA. Digits only.", "example": "823380597459265" } } }, "WhatsappFundingResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappFunding" } } }, "WhatsappFundingListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappFunding" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "WhatsappBillingUsage": { "type": "object", "required": [ "start_time", "end_time", "time_basis", "currency", "charge_scope", "totals", "breakdown" ], "properties": { "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "time_basis": { "type": "string", "description": "The window measures when charges were recorded, not when Meta delivered the original messages.", "const": "recorded_at" }, "currency": { "type": "string", "example": "USD" }, "charge_scope": { "type": "string", "description": "Charges recorded by Kapso, not Meta's complete invoice or native-currency costs.", "const": "kapso_recorded_charges" }, "totals": { "type": "object", "required": [ "customer_charge_micro_usd" ], "properties": { "customer_charge_micro_usd": { "type": "integer", "description": "Sum of every `breakdown` charge, in micro-USD (`1000000` is USD 1). Signed corrections are included, so a correction-only window can be negative.", "example": 115000 } } }, "breakdown": { "type": "array", "description": "One entry per recorded usage kind, each with its own freshness. New kinds can be added; do not rely on array order, and handle unknown `usage_kind` values. Use `totals` for the overall recorded amount.", "items": { "$ref": "#/components/schemas/WhatsappBillingUsageBreakdownItem" } } } }, "WhatsappBillingUsageBreakdownItem": { "type": "object", "required": [ "usage_kind", "customer_charge_micro_usd", "sync" ], "properties": { "usage_kind": { "type": "string", "description": "Extensible machine-readable kind of recorded charge.", "example": "messaging" }, "customer_charge_micro_usd": { "type": "integer", "description": "Recorded charge for this kind, in micro-USD.", "example": 90000 }, "billable_messages": { "type": "integer", "description": "Messaging only. Calling reports aggregate fees, not call counts or minutes.", "example": 1 }, "coverage": { "type": "object", "description": "Calling only. Current active-attachment currency support. Support does not promise billing activation, working credentials or complete observations, and historical charges stay in the total after support is lost.", "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "description": "- `supported`: every active attachment is a USD WABA.\n- `partial`: mixed USD and non-USD attachments. Fresh USD observations do\n not establish zero calling cost for the non-USD WABAs.\n- `unsupported`: no USD attachment.\n- `not_available`: no active attachment.\n", "enum": [ "supported", "partial", "unsupported", "not_available" ] }, "reason": { "type": "string", "nullable": true, "description": "`calling_requires_usd_waba` for `partial`/`unsupported`, `no_active_attachment` for `not_available`, null for `supported`.", "example": "calling_requires_usd_waba" } } }, "sync": { "$ref": "#/components/schemas/WhatsappBillingUsageSync" } } }, "WhatsappBillingUsageSync": { "type": "object", "description": "Current observation health for this usage kind, not completeness of the requested range.", "required": [ "status", "last_synced_at", "usage_through" ], "properties": { "status": { "type": "string", "description": "- `synced`: every relevant account is fresh. Messaging settles within 15\n minutes; calling coverage is under one hour old.\n- `delayed`: evidence exists but at least one account is older than that\n boundary. The boundary labels freshness, not a calling authorization\n cutoff or a promise that every cold account is polled on that cadence.\n- `unknown`: at least one relevant account has no successful observation.\n- `not_available`: no coverage applies, for example a direct managed-billing\n account for messaging, or no active USD attachment for calling. Totals are\n still returned.\n", "enum": [ "synced", "delayed", "unknown", "not_available" ] }, "last_synced_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Messaging - oldest latest successful settlement across the relevant accounts. Always null for calling, which stores a coverage watermark instead of a settlement completion timestamp." }, "usage_through": { "type": "string", "format": "date-time", "nullable": true, "description": "Conservative common end of processed coverage. For messaging, the common end of the processed query windows capped at fetch completion; for calling, the oldest reconciled coverage watermark across USD attachments. Not a guarantee that Meta has reported everything for that period." } } }, "WhatsappBillingUsageResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappBillingUsage" } } }, "WhatsappFundingOperation": { "type": "object", "required": [ "operation_id", "business_portfolio_id", "status", "requested_at", "message" ], "properties": { "operation_id": { "type": "string", "format": "uuid" }, "business_portfolio_id": { "type": "string", "example": "30458864570425307" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "superseded" ] }, "requested_at": { "type": "string", "format": "date-time" }, "message": { "type": "string", "example": "Portfolio funding revocation is queued." } } }, "WhatsappFundingOperationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhatsappFundingOperation" } } } }, "responses": { "UnauthorizedError": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundError": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PaymentRequiredError": { "description": "Feature requires a paid plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "paths": { "/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Returns customers in your project, most recent first.", "operationId": "listCustomers", "parameters": [ { "name": "name_contains", "in": "query", "description": "Filter by name substring", "schema": { "type": "string" } }, { "name": "external_customer_id", "in": "query", "description": "Filter by your customer ID", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "description": "RFC 5988 pagination links", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" }, "examples": { "basic": { "value": { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme Corp", "external_customer_id": "cus_abc123", "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:00:00Z" }, { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "TechStart Inc", "external_customer_id": "cus_xyz789", "created_at": "2025-01-14T15:30:00Z", "updated_at": "2025-01-14T15:30:00Z" } ], "meta": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 2 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "operationId": "createCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateRequest" }, "examples": { "basic": { "value": { "customer": { "name": "Acme Corp", "external_customer_id": "cus_abc123" } } } } } } }, "responses": { "201": { "description": "Customer created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" }, "examples": { "created": { "value": { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme Corp", "external_customer_id": "cus_abc123", "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:00:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customers/{customer_id}": { "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Customers" ], "summary": "Get customer", "operationId": "getCustomer", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Customers" ], "summary": "Update customer", "operationId": "updateCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" }, "examples": { "update_name": { "value": { "customer": { "name": "Acme Corporation" } } } } } } }, "responses": { "200": { "description": "Customer updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Customers" ], "summary": "Delete customer", "operationId": "deleteCustomer", "responses": { "204": { "description": "Customer deleted" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/customers/{customer_id}/setup_links": { "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Setup Links" ], "summary": "List setup links", "description": "Get WhatsApp onboarding links for a customer, most recent first.", "operationId": "listCustomerSetupLinks", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "used", "expired", "revoked" ] } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupLinkListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "tags": [ "Setup Links" ], "summary": "Create setup link", "description": "Generate an onboarding setup for customers to connect their WhatsApp number.\n\nOpen the returned URL as a Kapso-hosted page, or use the returned token with `@kapso/sdk` when your Tech Provider app belongs to an active Kapso Multi-partner Solution. The setup can optionally provision a new number.\n", "operationId": "createCustomerSetupLink", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupLinkCreateRequest" }, "examples": { "minimal": { "summary": "Basic link", "value": { "setup_link": {} } }, "with_redirects": { "summary": "Custom success/failure URLs", "value": { "setup_link": { "success_redirect_url": "https://yourapp.com/whatsapp/success", "failure_redirect_url": "https://yourapp.com/whatsapp/failed" } } }, "embedded_sdk": { "summary": "Launch from a Tech Provider product with @kapso/sdk", "value": { "setup_link": { "allowed_origins": [ "https://app.example.com" ], "allowed_connection_types": [ "dedicated" ] } } }, "coexistence_only": { "summary": "Force coexistence mode", "value": { "setup_link": { "allowed_connection_types": [ "coexistence" ] } } }, "with_kapso_billing": { "summary": "Pay Meta fees with Kapso credits", "value": { "setup_link": { "meta_billing_mode": "partner_managed" } } }, "with_phone": { "summary": "Auto-provision number", "value": { "setup_link": { "provision_phone_number": true, "phone_number_area_code": "415", "phone_number_country_isos": [ "US" ] } } }, "branded": { "summary": "Custom brand colors", "value": { "setup_link": { "theme_config": { "primary_color": "#3b82f6", "primary_foreground_color": "#ffffff", "background_color": "#f9fafb", "text_color": "#111827", "border_color": "#d1d5db" } } } }, "reconnect": { "summary": "Reconnect an existing customer number", "value": { "setup_link": { "reconnect_phone_number": "+14155551234" } } } } } } }, "responses": { "201": { "description": "Setup link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupLinkCreateResponse" }, "examples": { "created": { "value": { "data": { "id": "7f8a9b1c-2d3e-4f5a-6b7c-8d9e0f1a2b3c", "status": "active", "created_at": "2025-01-15T10:00:00Z", "expires_at": "2025-02-14T10:00:00Z", "url": "https://app.kapso.ai/whatsapp/setup/aBcD123xyz456def789", "token": "aBcD123xyz456def789", "success_redirect_url": "https://yourapp.com/whatsapp/success", "failure_redirect_url": "https://yourapp.com/whatsapp/failed", "allowed_origins": [ "https://app.example.com" ], "allowed_connection_types": [ "coexistence", "dedicated" ], "meta_billing_mode": "customer_managed", "provision_phone_number": false, "phone_number_area_code": null, "phone_number_country_isos": [ "US" ], "reconnect_phone_number": null, "theme_config": { "primary_color": "#3b82f6", "primary_foreground_color": "#ffffff", "background_color": "#f9fafb", "text_color": "#111827", "border_color": "#d1d5db" }, "whatsapp_setup_status": "pending", "whatsapp_setup_error": null } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customers/{customer_id}/setup_links/{setup_link_id}": { "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "setup_link_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "tags": [ "Setup Links" ], "summary": "Update setup link", "operationId": "updateCustomerSetupLink", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupLinkUpdateRequest" }, "examples": { "revoke": { "summary": "Revoke link", "value": { "setup_link": { "status": "revoked" } } }, "extend": { "summary": "Extend expiration", "value": { "setup_link": { "expires_at": "2025-09-15T10:00:00Z" } } }, "rebrand": { "summary": "Update theme", "value": { "setup_link": { "theme_config": { "primary_color": "#10b981", "text_color": "#0f172a" } } } } } } } }, "responses": { "200": { "description": "Setup link updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupLinkResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List project webhooks", "description": "Get all webhooks for the project (both project-scoped and phone number-scoped), most recent first.", "operationId": "listWhatsappProjectWebhooks", "parameters": [ { "name": "kind", "in": "query", "description": "Filter by webhook kind", "schema": { "type": "string", "enum": [ "kapso", "meta" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create project webhook", "description": "Create a webhook for this project.\n\nTwo scoping options:\n- **Project-scoped**: Omit `phone_number_id` to receive project events only\n- **Number-scoped**: Include `phone_number_id` to receive message and conversation events for that number\n\nProject webhooks do not receive message or conversation events. Use a number-scoped webhook (or\n`POST /whatsapp/phone_numbers/{phone_number_id}/webhooks`) for those.\n\nSubscribing to `project.event` requires project events to be available on your plan.\n\nTwo webhook types:\n- **kapso**: Event-based webhooks with filtered events, buffering support, and Kapso payload format\n- **meta**: Raw Meta webhook forwarding - receives the exact payload Meta sends (requires `phone_number_id`)\n", "operationId": "createWhatsappProjectWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappProjectWebhookRequest" }, "examples": { "project_scoped": { "summary": "Project-wide webhook", "value": { "whatsapp_webhook": { "url": "https://api.acme.com/webhooks/whatsapp", "secret_key": "wh_sec_3kfj9dmfkg8s2", "events": [ "whatsapp.phone_number.created", "whatsapp.phone_number.deleted" ] } } }, "number_scoped": { "summary": "Number-specific webhook", "value": { "whatsapp_webhook": { "url": "https://api.acme.com/webhooks/whatsapp", "phone_number_id": "1234567890", "secret_key": "wh_sec_3kfj9dmfkg8s2", "events": [ "whatsapp.message.received", "whatsapp.message.sent" ] } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/webhooks/{webhook_id}": { "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Webhooks" ], "summary": "Get project webhook", "operationId": "getWhatsappProjectWebhook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update project webhook", "description": "Update a project webhook. Subscribing to `project.event` requires project events\nto be available on your plan.\n", "operationId": "updateWhatsappProjectWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookUpdateRequest" }, "examples": { "enable_buffering": { "summary": "Enable buffering", "value": { "whatsapp_webhook": { "buffer_enabled": true, "buffer_window_seconds": 5, "max_buffer_size": 20, "buffer_events": [ "whatsapp.message.received" ] } } }, "pause": { "summary": "Pause deliveries", "value": { "whatsapp_webhook": { "active": false } } }, "change_url": { "summary": "Update endpoint", "value": { "whatsapp_webhook": { "url": "https://api.acme.com/webhooks/whatsapp-v2" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete project webhook", "operationId": "deleteWhatsappProjectWebhook", "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/webhooks/{webhook_id}/test": { "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Webhooks" ], "summary": "Test project webhook", "description": "Send a test payload to the webhook endpoint.\n\nOptionally specify an `event_type` to test with a specific event payload. The event type must be one of the events the webhook is configured to receive.\n", "operationId": "testWhatsappProjectWebhook", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "Specific event type to test (must be configured on webhook)" } } }, "examples": { "default": { "summary": "Test with default event", "value": {} }, "specific_event": { "summary": "Test specific event", "value": { "event_type": "whatsapp.message.received" } } } } } }, "responses": { "200": { "description": "Test queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/phone_numbers": { "get": { "tags": [ "Phone Numbers" ], "summary": "List phone numbers", "description": "Get WhatsApp numbers in your project, most recent first.", "operationId": "listWhatsappPhoneNumbers", "parameters": [ { "name": "phone_number_id", "in": "query", "description": "Filter by Meta phone number ID", "schema": { "type": "string" } }, { "name": "business_account_id", "in": "query", "description": "Filter by WABA ID", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "messaging_enabled", "in": "query", "schema": { "type": "boolean" } }, { "name": "name_contains", "in": "query", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberListResponse" }, "examples": { "multiple": { "value": { "data": [ { "id": "1234567890", "internal_id": "4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d", "phone_number_id": "1234567890", "name": "Support Line", "business_account_id": "98765432109", "is_coexistence": false, "inbound_processing_enabled": true, "calls_enabled": false, "webhook_verified_at": "2025-01-14T15:10:00Z", "created_at": "2025-01-14T15:00:00Z", "updated_at": "2025-01-14T15:10:00Z", "display_name": "Support Line", "display_phone_number": "+1 555-123-4567", "display_phone_number_normalized": "15551234567", "verified_name": "Acme Corp", "quality_rating": "GREEN", "throughput_tier": "TIER_10K", "whatsapp_business_manager_messaging_limit": "10000", "customer_id": "3f2e1d0c-9b8a-7f6e-5d4c-3b2a1f0e9d8c", "code_verification_status": "COMPLETED", "name_status": "APPROVED", "status": "CONNECTED", "is_official_business_account": false, "is_pin_enabled": true } ], "meta": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 1 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/customers/{customer_id}/whatsapp/phone_numbers": { "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Phone Numbers" ], "summary": "Connect phone number", "description": "Connect a WhatsApp number to this customer using Meta credentials.\n\nGet credentials from Meta's App Dashboard after completing embedded signup or manual setup.\n", "operationId": "createCustomerWhatsappPhoneNumber", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberCreateRequest" }, "examples": { "production": { "summary": "Production number", "value": { "whatsapp_phone_number": { "name": "Support Line", "kind": "production", "phone_number_id": "1234567890", "business_account_id": "98765432109", "access_token": "EAABsbCS...long-lived-token", "webhook_destination_url": "https://yourapp.com/webhooks/whatsapp", "webhook_verify_token": "your-verify-token", "inbound_processing_enabled": true, "calls_enabled": false } } }, "sandbox": { "summary": "Test with sandbox", "value": { "whatsapp_phone_number": { "name": "Test Number", "kind": "sandbox", "phone_number_id": "sandbox", "business_account_id": "sandbox", "access_token": "sandbox" } } } } } } }, "responses": { "201": { "description": "Phone number connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberResponse" }, "examples": { "created": { "value": { "data": { "id": "1234567890", "internal_id": "4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d", "phone_number_id": "1234567890", "name": "Support Line", "business_account_id": "98765432109", "is_coexistence": false, "inbound_processing_enabled": true, "calls_enabled": false, "webhook_verified_at": "2025-01-15T10:10:00Z", "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:10:00Z", "customer_id": "3f2e1d0c-9b8a-7f6e-5d4c-3b2a1f0e9d8c", "display_name": "Support Line", "display_phone_number": "+1 555-123-4567", "display_phone_number_normalized": "15551234567", "verified_name": "Acme Corp", "quality_rating": "GREEN", "code_verification_status": "COMPLETED", "name_status": "APPROVED", "status": "CONNECTED", "throughput_tier": "TIER_10K", "whatsapp_business_manager_messaging_limit": "10000", "is_official_business_account": false, "is_pin_enabled": true } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Phone limit reached or duplicate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/phone_numbers/{phone_number_id}": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "Meta phone number ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Phone Numbers" ], "summary": "Get phone number", "operationId": "getWhatsappPhoneNumber", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Phone Numbers" ], "summary": "Update phone number", "operationId": "updateWhatsappPhoneNumber", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberUpdateRequest" }, "examples": { "rotate_token": { "summary": "Rotate credentials", "value": { "whatsapp_phone_number": { "access_token": "EAABsbCS...new-token", "webhook_destination_url": "https://yourapp.com/webhooks/whatsapp" } } }, "toggle_calls": { "summary": "Enable voice calls", "value": { "whatsapp_phone_number": { "calls_enabled": true } } } } } } }, "responses": { "200": { "description": "Phone number updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Phone Numbers" ], "summary": "Delete phone number", "operationId": "deleteWhatsappPhoneNumber", "responses": { "204": { "description": "Phone number deleted" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/phone_numbers/{phone_number_id}/health": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Phone Numbers" ], "summary": "Check phone health", "description": "Health check via Meta APIs and Kapso services.\n\nResults are cached for 3 minutes per phone number, so repeated calls can\nreturn the same payload. Use `timestamp` to tell when the check actually\nran. The cache is invalidated early when the number's configuration\nchanges.\n\nIf a fresh check is already running for the same number and does not\nfinish within 15 seconds, the response is `status: error` with an\n`error` message asking you to retry shortly.\n\nWhen a check keeps failing to read the phone number from Meta because of\nan access or token error, the result is held for longer: 5, then 15, then\n30, then 60 minutes. During that window the response repeats the last\npayload and adds `retry_after`. Rate limits, payment errors and transport\nfailures do not trigger this. A successful check clears `retry_after` and\nresets the delay, as does reconnecting the number or changing its\ncredentials.\n\nWhen Meta reports the number as `DISCONNECTED`, the overall `status` is\n`unhealthy` even if the other checks pass. Reconnect the number to\nrestore messaging. A missing or unrecognized connection status is\nreported as `UNKNOWN` and does not affect the overall status.\n\nHealth checks are limited to 5 requests per second and 60 requests per\nminute per project, shared across all API keys in the project. Over the\nlimit the request is rejected with `429` before Meta is called, and\n`Retry-After` tells you how many seconds to wait. Every response carries\nthe current counters in the `X-Health-RateLimit-*` headers.\n", "operationId": "getWhatsappPhoneNumberHealth", "responses": { "200": { "description": "Health status", "headers": { "X-Health-RateLimit-Second-Limit": { "description": "Requests allowed per second for this project", "schema": { "type": "integer" } }, "X-Health-RateLimit-Second-Remaining": { "description": "Requests left in the current second", "schema": { "type": "integer" } }, "X-Health-RateLimit-Minute-Limit": { "description": "Requests allowed per minute for this project", "schema": { "type": "integer" } }, "X-Health-RateLimit-Minute-Remaining": { "description": "Requests left in the current minute", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberHealthResponse" }, "examples": { "healthy": { "summary": "All checks pass", "value": { "status": "healthy", "timestamp": "2025-01-20T14:25:30Z", "checks": { "phone_number_access": { "passed": true, "details": { "verified_name": "My Business", "display_phone_number": "+1 555-123-4567", "quality_rating": "GREEN", "status": "CONNECTED", "throughput_tier": "TIER_10K", "id": "123456789012345" } }, "phone_number_connection": { "passed": true, "details": { "status": "CONNECTED" } }, "messaging_health": { "passed": true, "overall_status": "AVAILABLE", "details": { "can_send_message": "AVAILABLE", "entities": [ { "entity_type": "PHONE_NUMBER", "id": "123456789012345", "can_send_message": "AVAILABLE" }, { "entity_type": "WABA", "id": "987654321098765", "can_send_message": "AVAILABLE" }, { "entity_type": "BUSINESS", "id": "456789012345678", "can_send_message": "AVAILABLE" }, { "entity_type": "APP", "id": "789012345678901", "can_send_message": "AVAILABLE" } ] } }, "webhook_subscription": { "passed": true, "details": { "app_id": "789012345678901", "subscribed": true, "subscribed_fields": [ "messages", "message_template_status_update" ] } }, "webhook_verified": { "passed": true, "details": { "verified_at": "2025-01-15T10:30:00Z", "message": "Webhook successfully verified at 2025-01-15 10:30:00 UTC" } } } } }, "degraded": { "summary": "Limited messaging or webhook issues", "value": { "status": "degraded", "timestamp": "2025-01-15T10:00:00Z", "checks": { "phone_number_access": { "passed": true, "details": { "verified_name": "Acme Corp", "display_phone_number": "+1 555-123-4567", "quality_rating": "GREEN", "status": "CONNECTED", "throughput_tier": "TIER_10K" } }, "messaging_health": { "passed": false, "overall_status": "LIMITED", "details": { "can_send_message": "LIMITED", "entities": [ { "entity_type": "PHONE_NUMBER", "id": "1234567890", "can_send_message": "LIMITED", "additional_info": [ "There is an issue with the payment method. Template sending and business-initiated conversations are blocked.", "You can still send and receive messages within the 24-hour window." ] } ] } }, "webhook_subscription": { "passed": true, "details": { "app_id": "123456789", "subscribed": true, "subscribed_fields": [ "messages" ] } }, "webhook_verified": { "passed": false, "details": { "verified_at": null, "message": "Webhook not yet verified by Meta" } } } } }, "unhealthy_payment_method": { "summary": "Payment method error (Meta billing issue)", "description": "Must be resolved in Meta Business Manager, not in Kapso", "value": { "status": "unhealthy", "timestamp": "2025-01-20T16:45:15Z", "checks": { "phone_number_access": { "passed": true, "details": { "verified_name": "Demo Company", "display_phone_number": "+1 555-987-6543", "quality_rating": "GREEN", "status": "CONNECTED", "throughput_tier": "TIER_10K", "id": "998877665544332" } }, "messaging_health": { "passed": false, "overall_status": "BLOCKED", "details": { "can_send_message": "BLOCKED", "entities": [ { "entity_type": "PHONE_NUMBER", "id": "998877665544332", "can_send_message": "LIMITED", "additional_info": [ "Your display name has not been approved yet. Your message limit will increase after the display name is approved." ] }, { "entity_type": "WABA", "id": "556677889900112", "can_send_message": "BLOCKED", "errors": [ { "error_code": "141006", "error_description": "There is an error with the payment method. This will block business initiated conversations.", "possible_solution": "There was an error with your payment method. Please add a new payment method to the account." } ] }, { "entity_type": "BUSINESS", "id": "334455667788990", "can_send_message": "LIMITED" }, { "entity_type": "APP", "id": "112233445566778", "can_send_message": "AVAILABLE" } ] } }, "webhook_subscription": { "passed": true, "details": { "app_id": "112233445566778", "subscribed": true, "subscribed_fields": [ "messages" ] } }, "webhook_verified": { "passed": false, "details": { "verified_at": null, "message": "Webhook not yet verified by Meta" } } } } }, "unhealthy_disconnected": { "summary": "Number disconnected from Meta", "description": "Reconnect the number to restore messaging", "value": { "status": "unhealthy", "timestamp": "2026-09-17T09:12:00Z", "checks": { "phone_number_access": { "passed": true, "details": { "verified_name": "Demo Company", "display_phone_number": "+1 555-987-6543", "quality_rating": "GREEN", "status": "DISCONNECTED", "throughput_tier": "TIER_10K", "id": "998877665544332" } }, "phone_number_connection": { "passed": false, "details": { "status": "DISCONNECTED" } }, "messaging_health": { "passed": true, "overall_status": "AVAILABLE", "details": { "can_send_message": "AVAILABLE", "entities": [ { "entity_type": "PHONE_NUMBER", "id": "998877665544332", "can_send_message": "AVAILABLE" } ] } }, "webhook_subscription": { "passed": true, "details": { "app_id": "112233445566778", "subscribed": true, "subscribed_fields": [ "messages" ] } }, "webhook_verified": { "passed": true, "details": { "verified_at": "2026-09-01T08:15:30Z", "message": "Webhook successfully verified at 2026-09-01 08:15:30 UTC" } } } } }, "unhealthy_invalid_token": { "summary": "Invalid OAuth token", "description": "User needs to reconnect WhatsApp Business Account", "value": { "status": "unhealthy", "timestamp": "2025-01-20T18:22:45Z", "retry_after": "2025-01-20T18:27:45Z", "checks": { "phone_number_access": { "passed": false, "error": "Meta Graph API error: 400 - {\"error\" => {\"message\" => \"Invalid OAuth access token - Cannot parse access token\", \"type\" => \"OAuthException\", \"code\" => 190, \"fbtrace_id\" => \"ABC123xyz456\"}}" }, "messaging_health": { "passed": false, "error": "Meta Graph API error: 400 - {\"error\" => {\"message\" => \"Invalid OAuth access token - Cannot parse access token\", \"type\" => \"OAuthException\", \"code\" => 190, \"fbtrace_id\" => \"DEF789abc012\"}}" }, "webhook_subscription": { "passed": false, "error": "Meta Graph API error: 401 - {\"error\" => {\"message\" => \"Invalid OAuth access token - Cannot parse access token\", \"type\" => \"OAuthException\", \"code\" => 190, \"fbtrace_id\" => \"GHI345def678\"}}" }, "webhook_verified": { "passed": true, "details": { "verified_at": "2025-01-10T08:15:30Z", "message": "Webhook successfully verified at 2025-01-10 08:15:30 UTC" } } } } }, "error_response": { "summary": "Health check service error", "value": { "status": "error", "error": "Service temporarily unavailable", "timestamp": "2025-01-20T10:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "description": "Health check rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "X-Health-RateLimit-Second-Limit": { "schema": { "type": "integer" } }, "X-Health-RateLimit-Second-Remaining": { "schema": { "type": "integer" } }, "X-Health-RateLimit-Minute-Limit": { "schema": { "type": "integer" } }, "X-Health-RateLimit-Minute-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "value": { "error": "Rate limit exceeded", "message": "WhatsApp health checks are limited to 5 requests per second and 60 requests per minute per project." } } } } } } } } }, "/whatsapp/phone_numbers/{phone_number_id}/webhooks": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Get webhooks for this number, most recent first.", "operationId": "listWhatsappPhoneNumberWebhooks", "parameters": [ { "name": "url_contains", "in": "query", "description": "Filter by URL substring", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Filter by webhook kind", "schema": { "type": "string", "enum": [ "kapso", "meta" ] } }, { "name": "active", "in": "query", "description": "Filter by active status", "schema": { "type": "boolean" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Subscribe to WhatsApp events for this number.\n\nTwo webhook types available:\n- **kapso**: Event-based webhooks with filtered events, buffering support, and Kapso payload format\n- **meta**: Raw Meta webhook forwarding - receives the exact payload Meta sends, with X-Idempotency-Key header\n\nUse buffering (kapso only) to batch high-volume events like inbound messages. Without buffering, each message triggers an immediate webhook delivery.\n", "operationId": "createWhatsappPhoneNumberWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookRequest" }, "examples": { "basic": { "summary": "No buffering", "value": { "whatsapp_webhook": { "url": "https://api.acme.com/webhooks/whatsapp", "secret_key": "wh_sec_3kfj9dmfkg8s2", "events": [ "whatsapp.message.received", "whatsapp.message.sent" ], "active": true } } }, "buffered": { "summary": "Batch inbound messages", "value": { "whatsapp_webhook": { "url": "https://api.acme.com/webhooks/whatsapp", "secret_key": "wh_sec_3kfj9dmfkg8s2", "events": [ "whatsapp.message.received", "whatsapp.message.sent" ], "buffer_enabled": true, "buffer_window_seconds": 10, "max_buffer_size": 25, "buffer_events": [ "whatsapp.message.received" ], "headers": { "X-Webhook-Source": "kapso" } } } }, "with_inactivity": { "summary": "Track conversation inactivity", "value": { "whatsapp_webhook": { "url": "https://api.acme.com/webhooks/whatsapp", "secret_key": "wh_sec_3kfj9dmfkg8s2", "events": [ "whatsapp.message.received", "whatsapp.conversation.inactive" ], "inactivity_minutes": 30 } } }, "meta_forward": { "summary": "Forward raw Meta webhooks", "value": { "whatsapp_webhook": { "kind": "meta", "url": "https://api.acme.com/webhooks/whatsapp-meta", "secret_key": "your-signing-secret", "active": true } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookResponse" }, "examples": { "created": { "value": { "data": { "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8f7e6d5c4b", "url": "https://api.acme.com/webhooks/whatsapp", "events": [ "whatsapp.message.received", "whatsapp.message.sent" ], "active": true, "secret_key": "wh_sec_3kfj9dmfkg8s2", "headers": { "X-Webhook-Source": "kapso" }, "buffer_enabled": false, "buffer_window_seconds": null, "max_buffer_size": null, "buffer_events": [], "inactivity_minutes": 60, "project_id": "1d6ca0a3-91c2-4f13-8a94-28ddb0d5f2f3", "phone_number_id": "1234567890", "created_at": "2025-07-14T15:00:00Z", "updated_at": "2025-07-14T15:00:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/phone_numbers/{phone_number_id}/webhooks/{webhook_id}": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Webhooks" ], "summary": "Get webhook", "operationId": "getWhatsappPhoneNumberWebhook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook", "operationId": "updateWhatsappPhoneNumberWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookUpdateRequest" }, "examples": { "enable_buffering": { "summary": "Enable buffering", "value": { "whatsapp_webhook": { "buffer_enabled": true, "buffer_window_seconds": 5, "max_buffer_size": 20, "buffer_events": [ "whatsapp.message.received" ] } } }, "pause": { "summary": "Pause deliveries", "value": { "whatsapp_webhook": { "active": false } } }, "change_url": { "summary": "Update endpoint", "value": { "whatsapp_webhook": { "url": "https://api.acme.com/webhooks/whatsapp-v2" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappWebhookResponse" }, "examples": { "updated": { "value": { "data": { "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8f7e6d5c4b", "url": "https://api.acme.com/webhooks/whatsapp", "events": [ "whatsapp.message.received" ], "active": true, "secret_key": "wh_sec_3kfj9dmfkg8s2", "headers": {}, "buffer_enabled": true, "buffer_window_seconds": 5, "max_buffer_size": 20, "buffer_events": [ "whatsapp.message.received" ], "inactivity_minutes": 60, "project_id": "1d6ca0a3-91c2-4f13-8a94-28ddb0d5f2f3", "phone_number_id": "1234567890", "created_at": "2025-07-14T15:00:00Z", "updated_at": "2025-07-16T09:00:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "operationId": "deleteWhatsappPhoneNumberWebhook", "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/broadcasts": { "get": { "tags": [ "Broadcasts" ], "summary": "List broadcasts", "description": "Get broadcast campaigns, most recent first.", "operationId": "listWhatsappBroadcasts", "parameters": [ { "name": "phone_number_id", "in": "query", "description": "Filter by phone number", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "draft", "scheduled", "copying", "sending", "stopped", "completed", "failed" ] } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastListResponse" }, "examples": { "campaigns": { "value": { "data": [ { "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "name": "Weekend Sale 2025", "status": "completed", "started_at": "2025-07-15T10:00:00Z", "completed_at": "2025-07-15T11:30:00Z", "created_at": "2025-07-14T15:00:00Z", "updated_at": "2025-07-15T11:30:00Z", "phone_number_id": "1234567890", "whatsapp_template": { "id": "784203120908608", "meta_template_id": "784203120908608", "name": "weekend_sale_2025", "language_code": "en_US", "category": "MARKETING", "status": "approved", "quality_score": "GREEN", "components": [ { "type": "BODY", "text": "Hi {{name}}! Get {{discount}}% off this weekend only!", "example": { "body_text_named_params": [ { "param_name": "name", "example": "John" }, { "param_name": "discount", "example": "25" } ] } } ] }, "total_recipients": 1000, "sent_count": 950, "failed_count": 50, "delivered_count": 900, "read_count": 750, "responded_count": 120, "pending_count": 0, "response_rate": 12.6 }, { "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f", "name": "Product Launch Q3", "status": "sending", "started_at": "2025-07-16T09:00:00Z", "completed_at": null, "created_at": "2025-07-16T08:00:00Z", "updated_at": "2025-07-16T09:15:00Z", "phone_number_id": "0987654321", "whatsapp_template": { "id": "891234567890123", "meta_template_id": "891234567890123", "name": "product_launch_q3", "language_code": "en_US", "category": "MARKETING", "status": "approved", "quality_score": "YELLOW", "components": [ { "type": "BODY", "text": "New product alert! Check out our Q3 launch." } ] }, "total_recipients": 500, "sent_count": 250, "failed_count": 10, "delivered_count": 240, "read_count": 100, "responded_count": 15, "pending_count": 240, "response_rate": 6.0 } ], "meta": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 2 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "Broadcasts" ], "summary": "Create broadcast", "description": "Create a broadcast campaign in draft mode.\n\nWorkflow: create broadcast → add recipients → send. Broadcasts stay in draft until you call the send endpoint.\n", "operationId": "createWhatsappBroadcast", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastCreateRequest" }, "examples": { "meta_id": { "summary": "Create with Meta template ID (preferred)", "value": { "whatsapp_broadcast": { "name": "Weekend Sale 2025", "phone_number_id": "1234567890", "whatsapp_template_id": "784203120908608" } } }, "legacy": { "summary": "Legacy UUID (backward compatibility)", "value": { "whatsapp_broadcast": { "name": "Weekend Sale 2025", "phone_number_id": "1234567890", "whatsapp_template_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d" } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastResponse" }, "examples": { "draft": { "value": { "data": { "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "name": "Weekend Sale 2025", "status": "draft", "started_at": null, "completed_at": null, "created_at": "2025-07-14T15:00:00Z", "updated_at": "2025-07-14T15:00:00Z", "phone_number_id": "1234567890", "whatsapp_template": { "id": "784203120908608", "meta_template_id": "784203120908608", "name": "weekend_sale_2025", "language_code": "en_US", "category": "MARKETING", "status": "approved", "quality_score": "GREEN", "components": [ { "type": "BODY", "text": "Hi {{name}}! Get {{discount}}% off this weekend only!", "example": { "body_text_named_params": [ { "param_name": "name", "example": "John" }, { "param_name": "discount", "example": "25" } ] } } ] }, "total_recipients": 0, "sent_count": 0, "failed_count": 0, "delivered_count": 0, "read_count": 0, "responded_count": 0, "pending_count": 0, "response_rate": 0.0 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Phone number or template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/broadcasts/{broadcast_id}": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Broadcasts" ], "summary": "Get broadcast", "operationId": "getWhatsappBroadcast", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastResponse" }, "examples": { "sending": { "value": { "data": { "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "name": "Weekend Sale 2025", "status": "sending", "started_at": "2025-07-15T10:00:00Z", "stopped_at": null, "completed_at": null, "created_at": "2025-07-14T15:00:00Z", "updated_at": "2025-07-15T10:30:00Z", "phone_number_id": "1234567890", "whatsapp_template": { "id": "784203120908608", "meta_template_id": "784203120908608", "name": "weekend_sale_2025", "language_code": "en_US", "category": "MARKETING", "status": "approved", "quality_score": "UNKNOWN", "components": [ { "type": "BODY", "text": "Hi {{name}}! Get {{discount}}% off this weekend only!", "example": { "body_text_named_params": [ { "param_name": "name", "example": "John" }, { "param_name": "discount", "example": "25" } ] } } ] }, "total_recipients": 1000, "sent_count": 650, "failed_count": 50, "delivered_count": 600, "read_count": 320, "responded_count": 45, "pending_count": 300, "response_rate": 6.9 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Broadcasts" ], "summary": "Update broadcast status", "description": "Update a broadcast status.\n\nSet `status` to `stopped` to stop a broadcast that is currently sending. Pending recipients remain pending and no new sends are started.\n\nSet `status` to `draft` to cancel a scheduled broadcast and clear its schedule.\n", "operationId": "updateWhatsappBroadcastStatus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastUpdateRequest" }, "examples": { "stop": { "summary": "Stop a sending broadcast", "value": { "whatsapp_broadcast": { "status": "stopped" } } }, "return_to_draft": { "summary": "Return a scheduled broadcast to draft", "value": { "whatsapp_broadcast": { "status": "draft" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastResponse" }, "examples": { "stopped": { "value": { "data": { "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "name": "Weekend Sale 2025", "status": "stopped", "scheduled_at": null, "started_at": "2025-07-15T10:00:00Z", "stopped_at": "2025-07-15T10:12:30Z", "completed_at": null, "created_at": "2025-07-14T15:00:00Z", "updated_at": "2025-07-15T10:12:30Z", "phone_number_id": "1234567890", "whatsapp_template": null, "total_recipients": 1000, "sent_count": 650, "failed_count": 50, "delivered_count": 600, "read_count": 320, "responded_count": 45, "pending_count": 300, "response_rate": 6.9 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/broadcasts/{broadcast_id}/recipients": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Broadcasts" ], "summary": "List recipients", "description": "Get recipients for this broadcast with delivery status.", "operationId": "listWhatsappBroadcastRecipients", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastRecipientListResponse" }, "examples": { "recipients": { "value": { "data": [ { "id": "8c9d0e1f-2a3b-4c5d-6e7f-8a9b0c1d2e3f", "phone_number": "14155550123", "status": "sent", "sent_at": "2025-07-15T10:05:23Z", "delivered_at": "2025-07-15T10:05:30Z", "read_at": "2025-07-15T10:12:45Z", "responded_at": "2025-07-15T10:15:00Z", "created_at": "2025-07-15T10:00:00Z", "updated_at": "2025-07-15T10:15:00Z", "template_components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "first_name", "text": "Alicia" }, { "type": "text", "parameter_name": "discount_code", "text": "SAVE25" } ] } ] }, { "id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e", "phone_number": "14155550124", "status": "failed", "sent_at": "2025-07-15T10:05:30Z", "failed_at": "2025-07-15T10:05:32Z", "error_message": "Invalid phone number", "error_details": { "error_class": "WhatsappApiError", "code": 131047, "http_status": 400, "fbtrace_id": "A1bCd2EfGhIjKlMnOpQrSt" }, "created_at": "2025-07-15T10:00:10Z", "updated_at": "2025-07-15T10:05:32Z", "template_components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "first_name", "text": "Jane" }, { "type": "text", "parameter_name": "discount", "text": "SAVE40" } ] } ] } ], "meta": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 2 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "tags": [ "Broadcasts" ], "summary": "Add recipients", "description": "Add up to 1000 recipients to a draft broadcast. Duplicates are skipped.\n\nRecipients use Meta's component syntax with body, header, and button components.\n", "operationId": "addWhatsappBroadcastRecipients", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastRecipientsAddRequest" }, "examples": { "body_params": { "summary": "Body text parameters", "value": { "whatsapp_broadcast": { "recipients": [ { "phone_number": "+14155550123", "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "first_name", "text": "John" }, { "type": "text", "parameter_name": "discount", "text": "SAVE50" } ] } ] }, { "phone_number": "+14155550124", "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "first_name", "text": "Jane" }, { "type": "text", "parameter_name": "discount", "text": "SAVE40" } ] } ] } ] } } }, "with_buttons": { "summary": "Body params with dynamic button URL", "value": { "whatsapp_broadcast": { "recipients": [ { "phone_number": "+14155550123", "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "first_name", "text": "Alicia" }, { "type": "text", "parameter_name": "discount_code", "text": "SAVE25" } ] }, { "type": "button", "sub_type": "url", "index": 0, "parameters": [ { "type": "text", "text": "promo-code-12345" } ] } ] } ] } } }, "with_media": { "summary": "Media header with body params", "value": { "whatsapp_broadcast": { "recipients": [ { "phone_number": "+14155550123", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://cdn.acme.com/promo-banner.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "parameter_name": "first_name", "text": "Alicia" }, { "type": "text", "parameter_name": "discount_code", "text": "SAVE25" } ] } ] } ] } } } } } } }, "responses": { "201": { "description": "Added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastRecipientsAddResponse" }, "examples": { "summary": { "value": { "data": { "added": 495, "duplicates": 5, "errors": [ "Recipient 3: template parameters invalid - requires 2 parameters but got 1", "Recipient 7: invalid phone number format" ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Broadcasts" ], "summary": "Clear recipients", "description": "Remove all recipients from a draft or scheduled broadcast.\n\nClearing recipients from a scheduled broadcast also returns it to draft and clears `scheduled_at`.\n", "operationId": "clearWhatsappBroadcastRecipients", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/broadcasts/{broadcast_id}/send": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Broadcasts" ], "summary": "Send broadcast", "description": "Start sending messages immediately. This is asynchronous - use GET /broadcasts/{id} to monitor progress.", "operationId": "sendWhatsappBroadcast", "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastSendResponse" }, "examples": { "accepted": { "value": { "data": { "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "status": "sending", "scheduled_at": null, "started_at": "2025-10-12T17:03:21Z", "stopped_at": null, "completed_at": null } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/broadcasts/{broadcast_id}/schedule": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Broadcasts" ], "summary": "Schedule broadcast", "description": "Schedule a broadcast to send at a future time. The broadcast must be in draft status and have recipients.", "operationId": "scheduleWhatsappBroadcast", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduled_at" ], "properties": { "scheduled_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp with timezone. Must be in the future." } } }, "examples": { "schedule": { "value": { "scheduled_at": "2025-10-12T17:00:00Z" } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastSendResponse" }, "examples": { "scheduled": { "value": { "data": { "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "status": "scheduled", "scheduled_at": "2025-10-12T17:00:00Z", "started_at": null, "stopped_at": null, "completed_at": null } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/broadcasts/{broadcast_id}/cancel": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Broadcasts" ], "summary": "Cancel scheduled broadcast", "description": "Cancel a scheduled broadcast and return it to draft status. Only works for broadcasts in scheduled status.", "operationId": "cancelWhatsappBroadcast", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBroadcastSendResponse" }, "examples": { "cancelled": { "value": { "data": { "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "status": "draft", "scheduled_at": null, "started_at": null, "stopped_at": null, "completed_at": null } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/messages": { "get": { "tags": [ "Messages" ], "summary": "List messages", "description": "Query WhatsApp messages across all conversations. Results are returned newest first. Use cursor pagination (`limit`, `after`, `before`) to traverse large message histories efficiently.\n", "operationId": "listWhatsappMessages", "parameters": [ { "name": "phone_number_id", "in": "query", "description": "Filter by WhatsApp phone number ID", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "description": "Filter by conversation ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "phone_number", "in": "query", "description": "Filter by contact phone number (partial match)", "schema": { "type": "string" } }, { "name": "business_scoped_user_id", "in": "query", "description": "Filter by exact WhatsApp business-scoped user ID", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Filter by message direction", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "status", "in": "query", "description": "Filter by message status", "schema": { "type": "string", "enum": [ "pending", "sent", "delivered", "read", "failed" ] } }, { "name": "message_type", "in": "query", "description": "Filter by message type", "schema": { "type": "string" } }, { "name": "has_media", "in": "query", "description": "Filter messages with media attachments", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Maximum number of results per cursor-paginated page (default 20, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Cursor for the previous page (Base64 encoded).", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for the next page (Base64 encoded).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessageListResponse" }, "examples": { "messages": { "value": { "data": [ { "id": "wamid.HBgMMTIzNDU2Nzg5MBUCABIYGTA5RTlCQkI2NTI3", "timestamp": "1705395000", "type": "text", "from": "14155550123", "text": { "body": "Hello, I need help with my order" }, "kapso": { "direction": "inbound", "status": "delivered", "processing_status": "processed", "origin": "cloud_api", "phone_number": "14155550123", "phone_number_id": "123456789012345", "has_media": false, "whatsapp_conversation_id": "c63ced48-1283-4d55-8c8d-930f525aa0e5", "contact_name": "Alicia", "content": "Hello, I need help with my order" } } ], "paging": { "cursors": { "before": "eyJ2YWx1ZXMiOlsiMjAyNi0wMy0yNlQxNTowNTowMC4wMDAwMDBaIiwiMzQzMCJdLCJjb2x1bW5zIjpbImNyZWF0ZWRfYXQiLCJpZCJdfQ==", "after": "eyJ2YWx1ZXMiOlsiMjAyNi0wMy0yNlQxNTowMDowMC4wMDAwMDBaIiwiMzQyMSJdLCJjb2x1bW5zIjpbImNyZWF0ZWRfYXQiLCJpZCJdfQ==" }, "next": "eyJ2YWx1ZXMiOlsiMjAyNi0wMy0yNlQxNTowMDowMC4wMDAwMDBaIiwiMzQyMSJdLCJjb2x1bW5zIjpbImNyZWF0ZWRfYXQiLCJpZCJdfQ==", "previous": null } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/whatsapp/messages/{message_id}": { "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "WhatsApp message ID (WAMID)", "schema": { "type": "string" }, "example": "wamid.HBgMMTIzNDU2Nzg5MBUCABIYGTA5RTlCQkI2NTI3" } ], "get": { "tags": [ "Messages" ], "summary": "Get message", "description": "Retrieve a single message by its WhatsApp message ID (WAMID).", "operationId": "getWhatsappMessage", "responses": { "200": { "description": "Message details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessageResponse" }, "examples": { "message": { "value": { "data": { "id": "wamid.HBgMMTIzNDU2Nzg5MBUCABIYGTA5RTlCQkI2NTI3", "timestamp": "1705395000", "type": "text", "from": "14155550123", "text": { "body": "Hello, I need help with my order" }, "kapso": { "direction": "inbound", "status": "read", "processing_status": "processed", "origin": "cloud_api", "phone_number": "14155550123", "phone_number_id": "123456789012345", "has_media": false, "whatsapp_conversation_id": "c63ced48-1283-4d55-8c8d-930f525aa0e5", "contact_name": "Alicia", "content": "Hello, I need help with my order", "statuses": [ { "id": "wamid.HBgMMTIzNDU2Nzg5MBUCABIYGTA5RTlCQkI2NTI3", "status": "delivered", "timestamp": "1705395005", "recipient_id": "14155550123" }, { "id": "wamid.HBgMMTIzNDU2Nzg5MBUCABIYGTA5RTlCQkI2NTI3", "status": "read", "timestamp": "1705395300", "recipient_id": "14155550123" } ] } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "description": "Query WhatsApp conversations with filters. Results are returned by latest activity first and use cursor pagination.", "operationId": "listWhatsappConversations", "parameters": [ { "name": "phone_number_id", "in": "query", "description": "Filter by WhatsApp phone number ID", "schema": { "type": "string" } }, { "name": "phone_number", "in": "query", "description": "Filter by contact phone number (partial match)", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by conversation status", "schema": { "type": "string", "enum": [ "active", "ended" ] } }, { "name": "assigned_user_id", "in": "query", "description": "Filter by active assignee user ID (must be a project member)", "schema": { "type": "string", "format": "uuid" } }, { "name": "unassigned", "in": "query", "description": "Filter conversations with no active assignment. Cannot be combined with `assigned_user_id`.", "schema": { "type": "boolean" } }, { "name": "created_after", "in": "query", "description": "Filter conversations created after this timestamp", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter conversations created before this timestamp", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_active_after", "in": "query", "description": "Filter conversations active after this timestamp", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_active_before", "in": "query", "description": "Filter conversations active before this timestamp", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Maximum number of results per cursor-paginated page (default 20, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Cursor for the previous page (Base64 encoded).", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for the next page (Base64 encoded).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappConversationListResponse" }, "examples": { "conversations": { "value": { "data": [ { "id": "c63ced48-1283-4d55-8c8d-930f525aa0e5", "phone_number": "14155550123", "status": "active", "last_active_at": "2025-07-16T09:45:00Z", "created_at": "2025-06-01T12:00:00Z", "updated_at": "2025-07-16T09:45:00Z", "metadata": {}, "phone_number_id": "1234567890", "kapso": { "contact_name": "Alicia", "messages_count": 42, "last_message_id": "wamid.HBgMMTIzNDU2", "last_message_type": "text", "last_message_timestamp": "2025-07-16T09:40:00Z", "last_message_text": "Thanks!", "last_inbound_at": "2025-07-16T09:35:10Z", "last_outbound_at": "2025-07-16T09:40:00Z" } } ], "paging": { "cursors": { "before": "eyJ2YWx1ZXMiOlsiMjAyNi0wNS0xNVQxMzowNTowMC4wMDAwMDBaIiwiYzYzY2VkNDgtMTI4My00ZDU1LThjOGQtOTMwZjUyNWFhMGU1Il0sImNvbHVtbnMiOlsibGFzdF9hY3RpdmVfYXQiLCJpZCJdfQ==", "after": "eyJ2YWx1ZXMiOlsiMjAyNi0wNS0xNVQxMjowNTowMC4wMDAwMDBaIiwiYzYzY2VkNDgtMTI4My00ZDU1LThjOGQtOTMwZjUyNWFhMGU1Il0sImNvbHVtbnMiOlsibGFzdF9hY3RpdmVfYXQiLCJpZCJdfQ==" }, "next": null, "previous": null } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/conversations/{conversation_id}": { "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Conversations" ], "summary": "Get conversation", "description": "Retrieve a single conversation with metadata.", "operationId": "getWhatsappConversation", "responses": { "200": { "description": "Conversation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappConversationResponse" }, "examples": { "conversation": { "value": { "data": { "id": "c63ced48-1283-4d55-8c8d-930f525aa0e5", "phone_number": "14155550123", "status": "active", "last_active_at": "2025-07-16T09:45:00Z", "created_at": "2025-06-01T12:00:00Z", "updated_at": "2025-07-16T09:45:00Z", "metadata": {}, "phone_number_id": "1234567890", "kapso": { "contact_name": "Alicia", "messages_count": 42, "last_message_id": "wamid.HBgMMTIzNDU2", "last_message_type": "text", "last_message_timestamp": "2025-07-16T09:40:00Z", "last_message_text": "Thanks!", "last_inbound_at": "2025-07-16T09:35:10Z", "last_outbound_at": "2025-07-16T09:40:00Z" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Conversations" ], "summary": "Update conversation status", "description": "Close completed conversations or reopen them for follow-ups.", "operationId": "updateWhatsappConversation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappConversationUpdateRequest" }, "examples": { "close": { "summary": "Close conversation", "value": { "whatsapp_conversation": { "status": "ended" } } }, "reopen": { "summary": "Reopen conversation", "value": { "whatsapp_conversation": { "status": "active" } } } } } } }, "responses": { "200": { "description": "Conversation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappConversationResponse" }, "examples": { "ended": { "summary": "Closed conversation", "value": { "data": { "id": "c63ced48-1283-4d55-8c8d-930f525aa0e5", "phone_number": "14155550123", "status": "ended", "last_active_at": "2025-07-16T09:45:00Z", "created_at": "2025-06-01T12:00:00Z", "updated_at": "2025-07-16T09:45:00Z", "metadata": {}, "phone_number_id": "1234567890", "kapso": { "contact_name": "Alicia", "messages_count": 42, "last_message_id": "wamid.HBgMMTIzNDU2", "last_message_type": "text", "last_message_timestamp": "2025-07-16T09:40:00Z", "last_message_text": "Thanks!", "last_inbound_at": "2025-07-16T09:35:10Z", "last_outbound_at": "2025-07-16T09:40:00Z" } } } }, "active": { "summary": "Reopened conversation", "value": { "data": { "id": "c63ced48-1283-4d55-8c8d-930f525aa0e5", "phone_number": "14155550123", "status": "active", "last_active_at": "2025-07-16T10:15:00Z", "created_at": "2025-06-01T12:00:00Z", "updated_at": "2025-07-16T10:15:00Z", "metadata": {}, "phone_number_id": "1234567890", "kapso": { "contact_name": "Alicia", "messages_count": 43, "last_message_id": "wamid.HBgMMTIzNDU3", "last_message_type": "text", "last_message_timestamp": "2025-07-16T10:15:00Z", "last_message_text": "Hey, one more thing...", "last_inbound_at": "2025-07-16T10:15:00Z", "last_outbound_at": "2025-07-16T09:40:00Z" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/conversations/{conversation_id}/assignments": { "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Conversations" ], "summary": "List conversation assignments", "description": "Get all assignments for a conversation, most recent first.", "operationId": "listConversationAssignments", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Assignments retrieved", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationAssignmentListResponse" }, "examples": { "success": { "value": { "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "created_by_user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "notes": "Handling customer inquiry about pricing", "active": true, "created_at": "2026-01-19T10:30:00Z" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "user_id": "e2d3c4b5-a697-8076-edcb-a09876543210", "created_by_user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "notes": null, "active": false, "created_at": "2026-01-18T14:20:00Z" } ], "meta": { "page": 1, "per_page": 25, "total_pages": 1, "total_count": 2 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "tags": [ "Conversations" ], "summary": "Create conversation assignment", "description": "Assign a conversation to a team member. Only one active assignment is allowed per conversation.\n\nThe user must be a member of the project.\n", "operationId": "createConversationAssignment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationAssignmentCreateRequest" }, "examples": { "with_notes": { "summary": "Assign with notes", "value": { "assignment": { "user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "notes": "Customer needs help with integration" } } }, "simple": { "summary": "Simple assignment", "value": { "assignment": { "user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321" } } } } } } }, "responses": { "201": { "description": "Assignment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationAssignmentResponse" }, "examples": { "success": { "value": { "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "created_by_user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "notes": "Customer needs help with integration", "active": true, "created_at": "2026-01-19T10:30:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "user_not_found": { "summary": "User not in project", "value": { "error": "User not found or not a member of this project" } }, "already_assigned": { "summary": "Conversation already assigned", "value": { "error": "Conversation already has an active assignment" } } } } } } } } }, "/whatsapp/conversations/{conversation_id}/assignments/{id}": { "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Conversations" ], "summary": "Get conversation assignment", "description": "Retrieve a specific assignment by ID.", "operationId": "getConversationAssignment", "responses": { "200": { "description": "Assignment retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationAssignmentResponse" }, "examples": { "success": { "value": { "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "created_by_user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "notes": "Handling customer inquiry", "active": true, "created_at": "2026-01-19T10:30:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Conversations" ], "summary": "Update conversation assignment", "description": "Update an assignment's notes, reassign to another user, or deactivate (unassign).\n\nSet `active: false` to unassign without deleting the assignment record.\n", "operationId": "updateConversationAssignment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationAssignmentUpdateRequest" }, "examples": { "update_notes": { "summary": "Update notes", "value": { "assignment": { "notes": "Customer issue resolved" } } }, "unassign": { "summary": "Unassign conversation", "value": { "assignment": { "active": false } } }, "reassign": { "summary": "Reassign to different user", "value": { "assignment": { "user_id": "e2d3c4b5-a697-8076-edcb-a09876543210" } } } } } } }, "responses": { "200": { "description": "Assignment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationAssignmentResponse" }, "examples": { "updated": { "value": { "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "created_by_user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "notes": "Customer issue resolved", "active": true, "created_at": "2026-01-19T10:30:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "user_not_found": { "summary": "User not in project", "value": { "error": "User not found or not a member of this project" } } } } } } } } }, "/whatsapp/phone_numbers/{phone_number_id}/display_name_requests": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Display Names" ], "summary": "List display name requests", "description": "View all display name change requests for this number, most recent first.", "operationId": "listWhatsappDisplayNameRequests", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Display name requests retrieved", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappDisplayNameRequestListResponse" }, "examples": { "multiple_requests": { "summary": "Recent requests with different statuses", "value": { "data": [ { "id": "2b0f4a1e-7a58-4a15-b0c9-0d7f1a2b3c4d", "phone_number_id": "1234567890", "requested_display_name": "Acme Support", "previous_display_name": "+1 555-123-4567", "status": "applied", "submitted_at": "2025-07-14T15:00:00Z", "reviewed_at": "2025-07-15T12:34:00Z", "applied_at": "2025-07-16T09:00:00Z", "meta_error_code": null, "meta_error_subcode": null, "meta_error_type": null, "meta_error_message": null }, { "id": "8c9d0e1f-2a3b-4c5d-6e7f-8a9b0c1d2e3f", "phone_number_id": "1234567890", "requested_display_name": "TechCorp Customer Service", "previous_display_name": "Acme Support", "status": "pending_review", "submitted_at": "2025-07-20T10:30:00Z", "reviewed_at": null, "applied_at": null, "meta_error_code": null, "meta_error_subcode": null, "meta_error_type": null, "meta_error_message": null }, { "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c", "phone_number_id": "1234567890", "requested_display_name": "ACME Inc", "previous_display_name": "+1 555-123-4567", "status": "declined", "submitted_at": "2025-06-15T08:00:00Z", "reviewed_at": "2025-06-16T14:22:00Z", "applied_at": null, "meta_error_code": 100, "meta_error_subcode": 2388135, "meta_error_type": "OAuthException", "meta_error_message": "Display name does not match business verification details" } ], "meta": { "current_page": 1, "total_pages": 1, "total_count": 3, "per_page": 20 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "tags": [ "Display Names" ], "summary": "Submit display name request", "description": "Request a display name change. Meta reviews most changes within 24-48 hours. Some names may be approved instantly.\n", "operationId": "createWhatsappDisplayNameRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappDisplayNameRequestCreate" }, "examples": { "basic": { "summary": "Business name", "value": { "display_name_request": { "new_display_name": "Acme Support" } } }, "instant": { "summary": "Instant approval scenario", "value": { "display_name_request": { "new_display_name": "Bella's Boutique" } } } } } } }, "responses": { "201": { "description": "Display name request submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappDisplayNameRequestResponse" }, "examples": { "pending": { "summary": "Awaiting Meta review", "value": { "data": { "id": "2b0f4a1e-7a58-4a15-b0c9-0d7f1a2b3c4d", "phone_number_id": "1234567890", "requested_display_name": "Acme Support", "previous_display_name": "+1 555-123-4567", "status": "pending_review", "submitted_at": "2025-07-14T15:00:00Z", "reviewed_at": null, "applied_at": null, "meta_error_code": null, "meta_error_subcode": null, "meta_error_type": null, "meta_error_message": null } } }, "instant": { "summary": "Approved instantly", "value": { "data": { "id": "9d0e1f2a-3b4c-5d6e-7f8a-9b0c1d2e3f4a", "phone_number_id": "1234567890", "requested_display_name": "Bella's Boutique", "previous_display_name": "+1 555-987-6543", "status": "available_without_review", "submitted_at": "2025-07-20T14:30:00Z", "reviewed_at": null, "applied_at": null, "meta_error_code": null, "meta_error_subcode": null, "meta_error_type": null, "meta_error_message": null } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/phone_numbers/{phone_number_id}/display_name_requests/{request_id}": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Display Names" ], "summary": "Retrieve display name request", "description": "Check status of a display name change request. Poll this endpoint to monitor Meta's review progress.", "operationId": "getWhatsappDisplayNameRequest", "responses": { "200": { "description": "Display name request details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappDisplayNameRequestResponse" }, "examples": { "approved": { "summary": "Approved and applied", "value": { "data": { "id": "2b0f4a1e-7a58-4a15-b0c9-0d7f1a2b3c4d", "phone_number_id": "1234567890", "requested_display_name": "Acme Support", "previous_display_name": "+1 555-123-4567", "status": "approved", "submitted_at": "2025-07-14T15:00:00Z", "reviewed_at": "2025-07-15T12:34:00Z", "applied_at": "2025-07-16T09:00:00Z", "meta_error_code": null, "meta_error_subcode": null, "meta_error_type": null, "meta_error_message": null } } }, "declined": { "summary": "Rejected with error details", "value": { "data": { "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c", "phone_number_id": "1234567890", "requested_display_name": "ACME Inc", "previous_display_name": "+1 555-123-4567", "status": "declined", "submitted_at": "2025-06-15T08:00:00Z", "reviewed_at": "2025-06-16T14:22:00Z", "applied_at": null, "meta_error_code": 100, "meta_error_subcode": 2388135, "meta_error_type": "OAuthException", "meta_error_message": "Display name does not match business verification details" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/media": { "post": { "tags": [ "Media" ], "summary": "Upload media", "description": "Upload media files for WhatsApp messaging from public URLs.\n\nSupports two delivery methods:\n- `meta_media`: Standard upload to Meta's media endpoint (30-day lifetime)\n- `meta_resumable_asset`: Resumable upload flow for profile pictures and large files\n\n**Security**: SSRF-protected - blocks private IPs, localhost, and metadata endpoints\n\n**Size limits**:\n- Images: 5 MB\n- Audio/Video: 16 MB\n- Documents: 100 MB\n\nRequests exceeding these limits fail immediately.\n", "operationId": "uploadWhatsappMedia", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaIngestRequest" }, "examples": { "meta_media": { "summary": "Standard media upload", "value": { "media_ingest": { "phone_number_id": "713452918527238", "source": "https://upload.wikimedia.org/wikipedia/commons/2/2f/Example.png", "delivery": "meta_media" } } }, "meta_resumable_asset": { "summary": "Resumable upload for profile picture", "value": { "media_ingest": { "phone_number_id": "713452918527238", "source": "https://cdn.acme.com/profile.jpg", "delivery": "meta_resumable_asset" } } }, "with_hints": { "summary": "Upload with optional filename and MIME hints", "value": { "media_ingest": { "phone_number_id": "713452918527238", "source": "https://cdn.acme.com/documents/invoice-2025-01.pdf", "delivery": "meta_media", "filename": "Invoice-January-2025.pdf", "mime_type": "application/pdf" } } }, "minimal": { "summary": "Minimal request (defaults to meta_media)", "value": { "media_ingest": { "phone_number_id": "713452918527238", "source": "https://cdn.acme.com/photo.jpg" } } } } } } }, "responses": { "200": { "description": "Media uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaIngestResponse" }, "examples": { "meta_media_success": { "summary": "Standard upload successful", "value": { "data": { "ingest_id": "8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d", "target": { "kind": "meta_media", "media_id": "1234567890123456" }, "resource": { "filename": "Example.png", "mime_type": "image/png", "size_bytes": 2335, "sha256": "69da8b7d9c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6", "source_url": "https://upload.wikimedia.org/wikipedia/commons/2/2f/Example.png" } } } }, "meta_resumable_asset_success": { "summary": "Resumable upload successful", "value": { "data": { "ingest_id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c", "target": { "kind": "meta_resumable_asset", "handle": "h:resumable-upload-handle-abc123xyz789" }, "resource": { "filename": "profile.jpg", "mime_type": "image/jpeg", "size_bytes": 45678, "sha256": "3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a", "source_url": "https://cdn.acme.com/profile.jpg" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_mime": { "summary": "Unsupported MIME type", "value": { "error": "Invalid MIME type: application/x-msdownload not supported by Meta" } }, "malformed_url": { "summary": "Invalid source URL", "value": { "error": "Source URL must be a valid HTTP or HTTPS URL" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sandbox_rejected": { "summary": "Sandbox configs not allowed", "value": { "error": "Sandbox WhatsApp configurations cannot upload media" } }, "private_ip_blocked": { "summary": "SSRF protection triggered", "value": { "error": "Cannot fetch from private IP addresses or localhost" } } } } } }, "404": { "description": "Phone number not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "value": { "error": "WhatsApp phone number not found or not accessible in this project" } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "size_exceeded": { "summary": "File exceeds size limit", "value": { "error": "File size 6291456 bytes exceeds limit of 5242880 bytes for image/png" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "value": { "error": "Meta API rate limit exceeded. Retry after 60 seconds" } } } } } }, "502": { "description": "Meta API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "meta_error": { "summary": "Meta rejected the upload", "value": { "error": "Meta API error: Invalid OAuth access token" } } } } } } } } }, "/whatsapp/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "Retrieve a paginated list of WhatsApp contacts for your project.", "operationId": "listWhatsappContactsPlatform", "parameters": [ { "name": "customer_id", "in": "query", "description": "Filter by associated customer ID", "schema": { "type": "string" } }, { "name": "customer_external_id", "in": "query", "description": "Filter by customer external ID", "schema": { "type": "string" } }, { "name": "has_customer", "in": "query", "description": "Filter by customer association (true/false)", "schema": { "type": "boolean" } }, { "name": "profile_name_contains", "in": "query", "description": "Filter by profile name (case-insensitive substring match)", "schema": { "type": "string" } }, { "name": "wa_id_contains", "in": "query", "description": "Filter by WhatsApp ID (substring match)", "schema": { "type": "string" } }, { "name": "business_scoped_user_id", "in": "query", "description": "Filter by exact WhatsApp business-scoped user ID", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "Filter contacts created after this ISO 8601 timestamp", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter contacts created before this ISO 8601 timestamp", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "Page number for legacy offset pagination. Deprecated — use cursor pagination (`limit`, `after`, `before`) instead. Maximum page: 50. Maximum window (`page` × `per_page`): 5,000. Requests exceeding these limits return a 400 error.\n", "deprecated": true, "schema": { "type": "integer", "default": 1, "maximum": 50 } }, { "name": "per_page", "in": "query", "description": "Items per page for legacy offset pagination.", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "limit", "in": "query", "description": "Maximum number of results per cursor-paginated page (default 20, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Cursor for the previous page (Base64 encoded).", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for the next page (Base64 encoded).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved contacts", "headers": { "X-Total": { "description": "Present only for legacy offset pagination responses.", "schema": { "type": "string" } }, "X-Total-Pages": { "description": "Present only for legacy offset pagination responses.", "schema": { "type": "string" } }, "X-Per-Page": { "description": "Present only for legacy offset pagination responses.", "schema": { "type": "string" } }, "X-Page": { "description": "Present only for legacy offset pagination responses.", "schema": { "type": "string" } }, "Link": { "description": "RFC 5988 pagination links for legacy offset pagination responses.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappContactListResponse" }, "examples": { "offsetPagination": { "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "wa_id": "15551234567", "profile_name": "John Doe", "display_name": "John (VIP)", "customer_id": "550e8400-e29b-41d4-a716-446655440000", "metadata": { "segment": "vip" }, "created_at": "2025-03-26T15:05:00.000000Z", "updated_at": "2025-03-26T15:05:00.000000Z" }, { "id": "223e4567-e89b-12d3-a456-426614174001", "wa_id": "15557654321", "profile_name": "Jane Smith", "display_name": null, "customer_id": null, "metadata": { "source": "sandbox" }, "created_at": "2025-03-26T15:00:00.000000Z", "updated_at": "2025-03-26T15:00:00.000000Z" } ], "meta": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 2 } } }, "cursorPagination": { "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "wa_id": "15551234567", "profile_name": "John Doe", "display_name": "John (VIP)", "customer_id": "550e8400-e29b-41d4-a716-446655440000", "metadata": { "segment": "vip" }, "created_at": "2025-03-26T15:05:00.000000Z", "updated_at": "2025-03-26T15:05:00.000000Z" }, { "id": "223e4567-e89b-12d3-a456-426614174001", "wa_id": "15557654321", "profile_name": "Jane Smith", "display_name": null, "customer_id": null, "metadata": { "source": "sandbox" }, "created_at": "2025-03-26T15:00:00.000000Z", "updated_at": "2025-03-26T15:00:00.000000Z" } ], "paging": { "cursors": { "before": "eyJ2YWx1ZXMiOlsiMjAyNS0wMy0yNlQxNTowNTowMC4wMDAwMDBaIiwiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIl0sImNvbHVtbnMiOlsiY3JlYXRlZF9hdCIsImlkIl19", "after": "eyJ2YWx1ZXMiOlsiMjAyNS0wMy0yNlQxNTowMDowMC4wMDAwMDBaIiwiMjIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAxIl0sImNvbHVtbnMiOlsiY3JlYXRlZF9hdCIsImlkIl19" }, "next": "eyJ2YWx1ZXMiOlsiMjAyNS0wMy0yNlQxNTowMDowMC4wMDAwMDBaIiwiMjIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAxIl0sImNvbHVtbnMiOlsiY3JlYXRlZF9hdCIsImlkIl19", "previous": null } } } } } } }, "400": { "description": "Legacy pagination limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "legacy_offset_pagination_limit_exceeded" }, "detail": { "type": "string", "example": "Page 51 exceeds the maximum supported legacy offset page (50). Use cursor pagination with limit, after, and before." }, "requested_page": { "type": "integer", "example": 51 }, "requested_per_page": { "type": "integer", "example": 100 }, "requested_window": { "type": "integer", "example": 5100 }, "max_page": { "type": "integer", "example": 50 }, "max_window": { "type": "integer", "example": 5000 }, "cursor_example": { "type": "string", "example": "https://api.kapso.ai/platform/v1/whatsapp/contacts?limit=100" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Contacts" ], "summary": "Create contact", "description": "Create a new WhatsApp contact.", "operationId": "createWhatsappContactPlatform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "type": "object", "required": [ "wa_id" ], "properties": { "wa_id": { "type": "string", "description": "WhatsApp ID (phone number in E.164 format)", "example": "+15551234567" }, "profile_name": { "type": "string" }, "display_name": { "type": "string" }, "customer_id": { "type": "string", "format": "uuid" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } }, "responses": { "201": { "description": "Contact created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappContactResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/contacts/{identifier}": { "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Contact UUID, WhatsApp phone number, business-scoped user ID\n(`US.13491208655302741918`), or parent business-scoped user ID\n(`US.ENT.11815799212886844830`).\n\nBSUIDs are matched verbatim, including the country prefix and period.\nA parent BSUID can be shared by several contacts in a project; the most\nrecently created match is returned.\n", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "get": { "tags": [ "Contacts" ], "summary": "Get contact", "description": "Retrieve a WhatsApp contact by UUID, phone number, or business-scoped user ID.", "operationId": "getWhatsappContactPlatform", "responses": { "200": { "description": "Contact retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappContactResponse" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Contacts" ], "summary": "Update contact", "description": "Update a WhatsApp contact's profile or metadata.", "operationId": "updateWhatsappContactPlatform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "wa_id": { "type": "string" }, "profile_name": { "type": "string" }, "display_name": { "type": "string" }, "customer_id": { "type": "string", "format": "uuid" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } }, "responses": { "200": { "description": "Contact updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappContactResponse" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Contacts" ], "summary": "Erase contact", "description": "Permanently erase a WhatsApp contact and all associated data (conversations, messages, media).\n\nThe erasure is processed asynchronously. A `204 No Content` response confirms the erasure job was queued.\n\nThe `identifier` can be the contact UUID, the WhatsApp phone number (E.164 format), or a business-scoped user ID.\n", "operationId": "eraseWhatsappContact", "responses": { "204": { "description": "Erasure queued successfully" }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid phone number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/contacts/{identifier}/marketing_preferences": { "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Contact UUID or WhatsApp phone number", "schema": { "type": "string" }, "example": "15551234567" } ], "get": { "tags": [ "Contacts" ], "summary": "List marketing preferences", "description": "List the contact's marketing message preference on each of your WhatsApp\nnumbers. One entry per number the contact has stopped or resumed\nmarketing on; an empty list means the contact never changed their\npreference and is subscribed everywhere.\n\nPreferences are read-only. Only the contact can change them, inside\nWhatsApp. While a preference is `stopped`, marketing template sends to\nthe contact on that number are refused with error code\n`marketing_preference_stopped`.\n", "operationId": "listWhatsappContactMarketingPreferences", "responses": { "200": { "description": "Marketing preferences retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappContactMarketingPreferenceListResponse" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/contacts/{identifier}/marketing_preferences/{phone_number_id}": { "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Contact UUID or WhatsApp phone number", "schema": { "type": "string" }, "example": "15551234567" }, { "name": "phone_number_id", "in": "path", "required": true, "description": "Meta phone number ID of one of your WhatsApp numbers", "schema": { "type": "string" }, "example": "123456789012345" } ], "get": { "tags": [ "Contacts" ], "summary": "Get marketing preference", "description": "Get the contact's marketing message preference on one WhatsApp number.\n\nA 404 with `\"Marketing preference not found\"` means the contact has no\nrecorded preference on that number — subscribed. Check the error string\nbefore treating a 404 as subscribed: a mistyped identifier returns\n`\"WhatsApp contact not found\"` and an unknown number returns\n`\"WhatsApp configuration not found\"`.\n", "operationId": "getWhatsappContactMarketingPreference", "responses": { "200": { "description": "Marketing preference retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappContactMarketingPreferenceResponse" } } } }, "404": { "description": "Contact, configuration, or preference not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/users": { "get": { "tags": [ "Users" ], "summary": "List project users", "description": "Returns all users who are members of your project.", "operationId": "listUsers", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersResponse" }, "examples": { "users": { "value": { "data": [ { "id": 1, "user_id": "f1e2d3c4-b5a6-9870-fedc-ba0987654321", "email": "owner@example.com", "name": "Owner User", "role": "owner" }, { "id": 2, "user_id": "e2d3c4b5-a697-8076-edcb-a09876543210", "email": "member@example.com", "name": "Member User", "role": "member" } ], "meta": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 2 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/webhook_deliveries": { "get": { "tags": [ "Webhook Deliveries" ], "summary": "List webhook deliveries", "description": "Returns webhook delivery attempts for your project, most recent first.", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "status", "in": "query", "description": "Filter by delivery status", "schema": { "type": "string", "enum": [ "pending", "delivered", "failed" ] } }, { "name": "event", "in": "query", "description": "Filter by event type", "schema": { "type": "string" } }, { "name": "webhook_id", "in": "query", "description": "Filter by webhook ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "errors_only", "in": "query", "description": "Only return failed deliveries", "schema": { "type": "boolean", "default": false } }, { "name": "period", "in": "query", "description": "Time period filter", "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "default": "24h" } }, { "name": "limit", "in": "query", "description": "Maximum number of results per cursor-paginated page (default 20, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Cursor for the previous page (Base64 encoded).", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for the next page (Base64 encoded).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/event-definitions": { "get": { "tags": [ "Events" ], "summary": "List project event definitions", "description": "Returns the event definitions registered for the project associated with\nyour API key. Definitions describe event names, meanings, and property\nschemas. Emitting a new event through `/events` can create a minimal\ndefinition automatically, but use this endpoint when you want to manage\ndefinition metadata directly.\n", "operationId": "listProjectEventDefinitions", "parameters": [ { "name": "include_archived", "in": "query", "description": "Include archived event definitions in the response. Archived definitions are hidden by default.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventDefinitionListResponse" }, "examples": { "definitions": { "summary": "Project event definitions found", "value": { "data": [ { "id": "880e8400-e29b-41d4-a716-446655440003", "name": "conversation.csat_scored", "description": "Customer satisfaction score for a conversation", "property_schema": { "score": { "type": "number" }, "reason": { "type": "string" } }, "last_seen_at": "2026-06-27T14:30:00Z", "created_at": "2026-06-20T10:00:00Z", "updated_at": "2026-06-20T10:00:00Z", "archived_at": null } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "Events" ], "summary": "Create or update a project event definition", "description": "Creates a definition for an event type. If a definition with the same\nname already exists, Kapso updates its editable metadata and returns it.\nIf the existing definition is archived, this request restores it.\nUse `/events` when you want to emit an actual event occurrence.\n", "operationId": "createProjectEventDefinition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventDefinitionCreateRequest" }, "examples": { "csat_definition": { "summary": "Conversation CSAT definition", "value": { "name": "conversation.csat_scored", "description": "Customer satisfaction score for a conversation", "property_schema": { "score": { "type": "number" }, "reason": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Existing definition updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventDefinitionResponse" } } } }, "201": { "description": "Definition created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventDefinitionResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/event-definitions/{id}": { "get": { "tags": [ "Events" ], "summary": "Retrieve a project event definition", "operationId": "getProjectEventDefinition", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventDefinitionResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Events" ], "summary": "Update a project event definition", "description": "Updates editable metadata for an event definition. Event names cannot be\nchanged after events have been recorded for the definition. Set `archived`\nto true to hide the definition from event tools and workflow selectors while\nretaining historical events; set it to false to restore it.\n", "operationId": "updateProjectEventDefinition", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventDefinitionUpdateRequest" }, "examples": { "update_schema": { "summary": "Update event schema", "value": { "description": "Customer satisfaction score for a conversation", "property_schema": { "score": { "type": "number" }, "resolved": { "type": "boolean" } }, "archived": false } } } } } }, "responses": { "200": { "description": "Definition updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventDefinitionResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Events" ], "summary": "Delete a project event definition and its events", "description": "Permanently deletes the event definition and all recorded event emissions\nassociated with it. This action cannot be undone. The endpoint returns\n`202 Accepted` while a background job performs the deletion; new events\nwith the same name are rejected while deletion is pending. To retain\nhistorical events while hiding the definition from new tools and workflow\nselectors, archive it with the PATCH endpoint instead.\n", "operationId": "deleteProjectEventDefinition", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Deletion queued for the definition and associated event emissions" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/events": { "get": { "tags": [ "Events" ], "summary": "List project events", "description": "Returns project-scoped events for the project associated with your API key,\nnewest first. Use filters to narrow by event name, linked WhatsApp\nconversation, or occurrence time.\n\nUse `limit`, `after`, and `before` for cursor pagination. Cursor-paginated\nresponses include `paging`; legacy offset responses include `meta`.\n", "operationId": "listProjectEvents", "parameters": [ { "name": "name", "in": "query", "description": "Filter by event name.", "schema": { "type": "string", "maxLength": 128, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$" }, "example": "conversation.csat_scored" }, { "name": "conversation_id", "in": "query", "description": "Filter by linked WhatsApp conversation ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "occurred_after", "in": "query", "description": "Only return events at or after this timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "occurred_before", "in": "query", "description": "Only return events at or before this timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Maximum number of results per cursor-paginated page (default 20, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Cursor for the previous page (Base64 encoded).", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for the next page (Base64 encoded).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventListResponse" }, "examples": { "events": { "summary": "Project events found", "value": { "data": [ { "id": "990e8400-e29b-41d4-a716-446655440004", "name": "conversation.csat_scored", "occurred_at": "2026-06-27T14:30:00Z", "conversation_id": "770e8400-e29b-41d4-a716-446655440002", "properties": { "score": 4, "reason": "Issue resolved in one reply" } } ], "paging": { "cursors": { "before": null, "after": null }, "next": null, "previous": null } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": [ "Events" ], "summary": "Emit a project event", "description": "Stores one timestamped project event. Event names must be lowercase and\nmay contain optional dot-separated segments; each segment starts with a\nlowercase letter and may contain lowercase letters, numbers, and\nunderscores. `conversation_id` is optional; include it when the\nevent belongs to a WhatsApp conversation.\n", "operationId": "createProjectEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventCreateRequest" }, "examples": { "csat_score": { "summary": "Conversation CSAT score", "value": { "name": "conversation.csat_scored", "occurred_at": "2026-06-27T14:30:00Z", "conversation_id": "770e8400-e29b-41d4-a716-446655440002", "properties": { "score": 4, "reason": "Issue resolved in one reply", "source": "workflow" } } } } } } }, "responses": { "201": { "description": "Event created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventResponse" }, "examples": { "created": { "summary": "Created project event", "value": { "data": { "id": "990e8400-e29b-41d4-a716-446655440004", "name": "conversation.csat_scored", "occurred_at": "2026-06-27T14:30:00Z", "conversation_id": "770e8400-e29b-41d4-a716-446655440002", "properties": { "score": 4, "reason": "Issue resolved in one reply", "source": "workflow" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api_logs": { "get": { "tags": [ "API Logs" ], "summary": "List API logs", "description": "Returns logs of external API calls made by your project, most recent first.", "operationId": "listApiLogs", "parameters": [ { "name": "endpoint", "in": "query", "description": "Filter by endpoint (partial match)", "schema": { "type": "string" } }, { "name": "status_code", "in": "query", "description": "Filter by HTTP status code", "schema": { "type": "integer" } }, { "name": "errors_only", "in": "query", "description": "Only return logs with status >= 400", "schema": { "type": "boolean", "default": false } }, { "name": "period", "in": "query", "description": "Time period filter", "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "default": "24h" } }, { "name": "limit", "in": "query", "description": "Maximum number of results per cursor-paginated page (default 20, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Cursor for the previous page (Base64 encoded).", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for the next page (Base64 encoded).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalApiLogListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/log_search": { "get": { "tags": [ "Log Search" ], "summary": "Search log events", "description": "Search log events for the project associated with your API key. Returns the same event payload shape used by the logs UI. Use POST when sending filters.", "operationId": "searchLogs", "parameters": [ { "name": "query", "in": "query", "description": "Free-text search query. Blank queries are allowed for browsing narrowed by source, filters, or problems_only.", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Time window to search. Use context with around to fetch nearby events.", "schema": { "type": "string", "enum": [ "24h", "7d", "context" ], "default": "24h" } }, { "name": "source", "in": "query", "description": "Log source to search. Use all to search every source.", "schema": { "type": "string", "enum": [ "all", "external_api_log", "whatsapp_webhook_event", "flow_event", "webhook_delivery" ], "default": "all" } }, { "name": "problems_only", "in": "query", "description": "Only return problem or error events.", "schema": { "type": "boolean", "default": false } }, { "name": "errors_only", "in": "query", "description": "Alias for problems_only.", "deprecated": true, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Maximum number of events returned.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Cursor returned as pagination.next_cursor from a previous response.", "schema": { "type": "string" } }, { "name": "around", "in": "query", "description": "Center a context search around this timestamp. Use with period=context.", "schema": { "type": "string", "format": "date-time" } }, { "name": "highlight_event_id", "in": "query", "description": "Include this event in the page when available.", "schema": { "type": "string" } }, { "name": "highlight_resource_id", "in": "query", "description": "Include an event for this resource in the page when available.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogSearchResponse" }, "examples": { "found": { "summary": "Log events found", "value": { "data": { "available": true, "source": "external_api_log", "window": { "since": "2026-07-06T12:00:00Z", "until": "2026-07-07T12:00:00Z" }, "events": [ { "id": "evt_1", "source": "external_api_log", "timestamp": "2026-07-07T11:59:00Z", "message": "POST /v1/messages", "http_method": "POST", "endpoint": "/v1/messages", "api_key_name": "Production key", "response_status": 422, "payload": { "error_message": "Graph API failed" } } ], "pagination": { "has_more": false, "next_cursor": null } } } }, "unavailable": { "summary": "Log search unavailable", "value": { "data": { "available": false, "events": [] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "description": "Invalid filters or search failure", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/LogSearchResponse" } ] }, "examples": { "invalid_filters": { "summary": "Invalid filters", "value": { "error": "filters must be an array of {key, value} entries or an object" } }, "search_failed": { "summary": "Search failure", "value": { "data": { "available": true, "events": [], "error": "log search failed", "code": "elastic_search_failed" } } } } } } } } }, "post": { "tags": [ "Log Search" ], "summary": "Search log events with filters", "description": "Search log events with the same project-scoped data and filter catalog used by the logs UI.", "operationId": "searchLogsWithFilters", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogSearchRequest" }, "examples": { "workflow_execution": { "summary": "Search a workflow execution", "value": { "query": "flow-execution-1", "period": "7d", "source": "flow_event", "filters": { "flow_execution_id": "flow-execution-1", "event_type": "step_failed" } } }, "api_errors": { "summary": "Search failed API calls", "value": { "query": "/messages", "period": "24h", "source": "external_api_log", "problems_only": true, "filters": { "endpoint_contains": "/messages" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogSearchResponse" }, "examples": { "found": { "summary": "Log events found", "value": { "data": { "available": true, "source": "flow_event", "window": { "since": "2026-07-01T12:00:00Z", "until": "2026-07-07T12:00:00Z" }, "events": [ { "id": "evt_2", "source": "flow_event", "timestamp": "2026-07-07T11:58:00Z", "message": "Flow Event step_failed agent_1", "flow_execution_id": "flow-execution-1", "flow_event_id": "flow-event-1", "step_identifier": "agent_1", "step_type": "FlowAgentStep", "error_message": "Tool call failed" } ], "pagination": { "has_more": false, "next_cursor": null } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "description": "Invalid filters or search failure", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/LogSearchResponse" } ] } } } } } } }, "/log_search/catalog": { "get": { "tags": [ "Log Search" ], "summary": "Get log search catalog", "description": "Returns the log source list, supported filter keys, and detail fields for the project associated with your API key.", "operationId": "getLogSearchCatalog", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogSearchCatalogResponse" }, "examples": { "catalog": { "summary": "Available catalog", "value": { "data": { "available": true, "catalog": { "sources": [ { "value": "all", "label": "All sources", "color": "transparent", "aliases": [ "all" ] }, { "value": "external_api_log", "label": "API", "color": "#2563eb", "aliases": [ "api", "external_api_log" ] } ], "filter_suggestions": [ { "key": "endpoint", "label": "endpoint:", "description": "API endpoint contains text", "param_key": "endpoint_contains", "sources": [ "external_api_log" ] } ], "detail_fields": [ "flow_execution_id", "event_type", "endpoint", "response_status" ] } } } }, "unavailable": { "summary": "Log search unavailable", "value": { "data": { "available": false, "events": [] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/provider_models": { "get": { "tags": [ "Provider Models" ], "summary": "List provider models", "description": "Returns available AI provider models.", "operationId": "listProviderModels", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderModelListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/inbox_embeds": { "get": { "tags": [ "Inbox Embeds" ], "summary": "List inbox embeds", "description": "Returns inbox embed access links for your project, most recent first. Raw tokens and embed URLs are not returned after creation.", "operationId": "listInboxEmbeds", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "revoked" ] } }, { "name": "scope_type", "in": "query", "schema": { "type": "string", "enum": [ "project", "customer", "phone_number" ] } }, { "name": "scope_id", "in": "query", "description": "Customer UUID for `customer`, WhatsApp `phone_number_id` for `phone_number`", "schema": { "type": "string" } }, { "name": "assigned_user_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxEmbedListResponse" }, "examples": { "phone_number": { "value": { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Support embed", "scope_type": "phone_number", "scope_id": "1234567890", "scope_name": "+1 415 555 1234", "assigned_user_id": null, "assigned_user_name": null, "status": "active", "allowed_origins": [ "https://app.example.com" ], "default_mode": "system", "language": "en", "expires_at": null, "last_used_at": null, "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:00:00Z" } ], "meta": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 1 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": [ "Inbox Embeds" ], "summary": "Create inbox embed", "description": "Create an embeddable inbox access link.\n\nThe response includes `token` and `embed_url` once. Store the embed URL when you create it; list, get, and update responses omit the secret.\n", "operationId": "createInboxEmbed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxEmbedCreateRequest" }, "examples": { "project": { "value": { "inbox_embed": { "name": "Project inbox", "scope_type": "project", "allowed_origins": [ "https://app.example.com" ], "language": "es" } } }, "customer": { "value": { "inbox_embed": { "name": "Customer inbox", "scope_type": "customer", "scope_id": "550e8400-e29b-41d4-a716-446655440000" } } }, "phone_number": { "value": { "inbox_embed": { "name": "Support number inbox", "scope_type": "phone_number", "scope_id": "1234567890", "default_mode": "system", "language": "es" } } } } } } }, "responses": { "201": { "description": "Inbox embed created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxEmbedCreatedResponse" }, "examples": { "created": { "value": { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Support number inbox", "scope_type": "phone_number", "scope_id": "1234567890", "scope_name": "+1 415 555 1234", "assigned_user_id": null, "assigned_user_name": null, "status": "active", "allowed_origins": [ "https://app.example.com" ], "default_mode": "system", "language": "es", "expires_at": null, "last_used_at": null, "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:00:00Z", "token": "inbox_token_example", "embed_url": "https://inbox.kapso.ai/embed/inbox_token_example" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/inbox_embeds/{inbox_embed_id}": { "parameters": [ { "name": "inbox_embed_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Inbox Embeds" ], "summary": "Get inbox embed", "description": "Returns an inbox embed without the raw token or embed URL.", "operationId": "getInboxEmbed", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxEmbedResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "tags": [ "Inbox Embeds" ], "summary": "Update inbox embed", "description": "Updates mutable settings. Scope cannot be changed; create a new embed for a different scope.", "operationId": "updateInboxEmbed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxEmbedUpdateRequest" }, "examples": { "update_origins": { "value": { "inbox_embed": { "allowed_origins": [ "https://app.example.com" ], "default_mode": "dark", "language": "es" } } } } } } }, "responses": { "200": { "description": "Inbox embed updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxEmbedResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Inbox Embeds" ], "summary": "Revoke inbox embed", "description": "Revokes the embed token immediately.", "operationId": "deleteInboxEmbed", "responses": { "204": { "description": "Inbox embed revoked" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/flows": { "get": { "tags": [ "WhatsApp Flows" ], "summary": "List flows", "description": "Returns WhatsApp flows in your project, most recent first.", "operationId": "listWhatsappFlows", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "business_account_id", "in": "query", "description": "Filter by WABA ID", "schema": { "type": "string" } }, { "name": "phone_number_id", "in": "query", "description": "Filter by phone number", "schema": { "type": "string" } }, { "name": "name_contains", "in": "query", "description": "Filter by name substring", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "WhatsApp Flows" ], "summary": "Create flow", "description": "Create a new WhatsApp Flow. By default creates a draft flow with a basic welcome screen.", "operationId": "createWhatsappFlow", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowCreateRequest" } } } }, "responses": { "201": { "description": "Flow created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/flows/{flow_id}": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "WhatsApp Flows" ], "summary": "Get flow", "operationId": "getWhatsappFlow", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/flows/{flow_id}/publish": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "WhatsApp Flows" ], "summary": "Publish flow", "description": "Publish a draft flow to make it available for use. Published flows cannot be unpublished.", "operationId": "publishWhatsappFlow", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number_id": { "type": "string", "description": "Override phone number (optional)" } } } } } }, "responses": { "200": { "description": "Flow published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "description": "Cannot publish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/flows/{flow_id}/setup_encryption": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "WhatsApp Flows" ], "summary": "Setup encryption", "description": "Set up flows encryption for the WABA associated with this flow. Required for data endpoints.", "operationId": "setupWhatsappFlowEncryption", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number_id": { "type": "string", "description": "Override phone number (optional)" } } } } } }, "responses": { "200": { "description": "Encryption configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowEncryptionSetupResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/flows/{flow_id}/versions": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "WhatsApp Flows" ], "summary": "List flow versions", "description": "Returns versions for a flow, most recent first.", "operationId": "listWhatsappFlowVersions", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Total": { "schema": { "type": "integer" } }, "X-Total-Pages": { "schema": { "type": "integer" } }, "X-Per-Page": { "schema": { "type": "integer" } }, "X-Page": { "schema": { "type": "integer" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowVersionListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "tags": [ "WhatsApp Flows" ], "summary": "Create flow version", "description": "Upload new flow JSON to create a new version. Syncs with Meta's API.", "operationId": "createWhatsappFlowVersion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowVersionCreateRequest" } } } }, "responses": { "201": { "description": "Version created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowVersionDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "validation_errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } }, "/whatsapp/flows/{flow_id}/versions/{version_id}": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "WhatsApp Flows" ], "summary": "Get flow version", "description": "Returns version details including the flow JSON.", "operationId": "getWhatsappFlowVersion", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowVersionDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/flows/{flow_id}/data_endpoint": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "WhatsApp Flows" ], "summary": "Get data endpoint", "description": "Get the data endpoint function configuration for a flow.", "operationId": "getWhatsappFlowDataEndpoint", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowDataEndpointResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "description": "No data endpoint configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "WhatsApp Flows" ], "summary": "Create/update data endpoint", "description": "Create or update the data endpoint function code. The function handles dynamic data for your flow.", "operationId": "createWhatsappFlowDataEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowDataEndpointCreateRequest" } } } }, "responses": { "200": { "description": "Data endpoint saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowDataEndpointResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "patch": { "tags": [ "WhatsApp Flows" ], "summary": "Attach an existing data endpoint function", "description": "Attach a deployed function from the same project and register the flow's\nKapso data endpoint with Meta. Multiple flows can share one function.\nRequires a WhatsApp phone number and flows encryption to be configured.\nDoes not create or deploy a function. Replaces any previous association\nwithout deleting the previous function or rotating the endpoint secret.\nUpdating or deploying a shared function affects every flow using it.\nPublished flows are automatically republished; a republish failure returns\nHTTP 200 with data.warning and leaves the new association in place.\n", "operationId": "updateWhatsappFlowDataEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowDataEndpointAttachRequest" } } } }, "responses": { "200": { "description": "Function attached and endpoint registered. Check data.warning for republish failures.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowDataEndpointAttachResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Flow or function not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Function is not deployed, phone number or encryption is missing, or Meta rejected the endpoint update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/flows/{flow_id}/data_endpoint/deploy": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "WhatsApp Flows" ], "summary": "Deploy data endpoint", "description": "Deploy the data endpoint function to Cloudflare Workers.", "operationId": "deployWhatsappFlowDataEndpoint", "responses": { "200": { "description": "Deployed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowDataEndpointResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/flows/{flow_id}/data_endpoint/register": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "WhatsApp Flows" ], "summary": "Register data endpoint with Meta", "description": "Register the deployed data endpoint URL with Meta. Requires flows encryption to be configured.", "operationId": "registerWhatsappFlowDataEndpoint", "responses": { "200": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowDataEndpointRegisterResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "description": "Encryption not configured or other error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/flows/{flow_id}/function_logs": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "WhatsApp Flows" ], "summary": "Get function logs", "description": "Get logs from the entire data endpoint function. If multiple flows share the function, results include activity from all of them, not just this flow.", "operationId": "getWhatsappFlowFunctionLogs", "parameters": [ { "name": "limit", "in": "query", "description": "Max logs to return (default 20, max 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowFunctionLogsResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "description": "No data endpoint configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/flows/{flow_id}/function_invocations": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "WhatsApp Flows" ], "summary": "Get function invocations", "description": "Get recent invocations of the entire data endpoint function. If multiple flows share the function, results include activity from all of them, not just this flow.", "operationId": "getWhatsappFlowFunctionInvocations", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "success", "failed" ] } }, { "name": "limit", "in": "query", "description": "Max invocations to return (default 10, max 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowFunctionInvocationsResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "description": "No data endpoint configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/findings": { "get": { "tags": [ "Findings" ], "summary": "List findings", "description": "Returns the findings for the project associated with your API key, most recently\nqualified first.\n\nOnly findings with status `candidate` or `open` are listed. Quiet findings,\ndismissed findings, and findings from sources Kapso does not read evidence from\nyet are omitted. To read a quiet or dismissed finding, fetch it by ID.\n\nFindings that belong to the same group are returned together on the same page,\nso a page can hold slightly more than `limit` items.\n", "operationId": "listFindings", "parameters": [ { "name": "limit", "in": "query", "description": "Findings per page. Must be between 1 and 25. Any other value returns `400`;\nit is not clamped.\n", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 20 } }, { "name": "after", "in": "query", "description": "Opaque cursor from a previous response's `paging.next`. Cannot be combined\nwith `before`.\n", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Opaque cursor from a previous response's `paging.previous`. Cannot be combined\nwith `after`.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingListResponse" }, "example": { "data": [ { "id": "8f14e45f-ceea-467a-9e1a-1b2c3d4e5f60", "signal_name": "conversation.user_frustrated", "direction": "rising", "status": "open", "affected_count": 42, "affected_unit": "conversations", "last_observed_at": "2026-08-26T09:12:00.000000Z", "related_findings_count": 2, "investigation": { "status": "completed", "retryable": false, "retry_reason": null, "completed_at": "2026-08-26T10:04:00.000000Z", "error_message": null, "cause_title": "Checkout step asks for the order number twice", "summary": "Users repeat themselves when the workflow loses the order number." }, "verification": null } ], "paging": { "cursors": { "before": "eyJ2ZXJzaW9uIjoxLCJ2YWx1ZXMiOlsiMjAyNi0wOC0yNlQwOToxMjowMC4wMDAwMDBaIl19", "after": "eyJ2ZXJzaW9uIjoxLCJ2YWx1ZXMiOlsiMjAyNi0wOC0yNVQwODowMDowMC4wMDAwMDBaIl19" }, "next": "eyJ2ZXJzaW9uIjoxLCJ2YWx1ZXMiOlsiMjAyNi0wOC0yNVQwODowMDowMC4wMDAwMDBaIl19", "previous": null } } } } }, "400": { "description": "Invalid `limit` or cursor, or `after` and `before` used together", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "Invalid limit parameter" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Findings is not enabled for this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "Findings is not enabled for this project.", "code": "findings_not_enabled" } } } } } } }, "/findings/{finding_id}": { "get": { "tags": [ "Findings" ], "summary": "Get a finding", "description": "Returns one finding with its metrics, related findings, latest verification,\nand latest investigation including causes and suggested fixes.\n\nUnlike listing, this reads any finding in the project — quiet and dismissed\nfindings included.\n\n`related_findings` is capped at 24 entries.\n", "operationId": "getFinding", "parameters": [ { "name": "finding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingDetailResponse" }, "example": { "data": { "id": "8f14e45f-ceea-467a-9e1a-1b2c3d4e5f60", "source_type": "project_event", "source_key": "conversation.user_frustrated", "signal_name": "conversation.user_frustrated", "direction": "rising", "status": "open", "affected_count": 42, "baseline_count": 11, "current_rate": 0.18, "baseline_rate": 0.05, "evidence_revision": 3, "last_observed_at": "2026-08-26T09:12:00.000000Z", "window_start_at": "2026-08-19T00:00:00.000000Z", "window_end_at": "2026-08-26T00:00:00.000000Z", "last_qualified_at": "2026-08-26T09:15:00.000000Z", "affected_unit": "conversations", "workflow_id": "c0ffee00-1111-4222-8333-444455556666", "workflow_name": "Order support", "verification": null, "related_findings": [], "investigation": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "status": "completed", "retryable": false, "retry_reason": null, "error_message": null, "created_at": "2026-08-26T09:40:00.000000Z", "completed_at": "2026-08-26T10:04:00.000000Z", "workflow_id": "c0ffee00-1111-4222-8333-444455556666", "workflow_name": "Order support", "result": { "summary": "Users repeat themselves when the workflow loses the order number.", "alternative_explanations": [], "coverage_limitations": [], "affected_components": [ "Order support" ], "causes": [ { "title": "Checkout step asks for the order number twice", "explanation": "The confirm node does not read the value captured earlier.", "confidence": "high", "evidence_references": [ { "source_type": "project_event", "source_id": "7d1f0e2a-3b4c-4d5e-9f60-718293a4b5c6", "observation": "User resent the order number after the confirm prompt.", "occurred_at": "2026-08-25T14:02:00.000000Z" } ] } ], "suggested_fixes": [ { "title": "Reuse the captured order number in the confirm node", "priority": "primary", "category": "workflow", "change": "Read `order_number` from state instead of prompting again.", "verification": "Frustration events should drop below the 5% baseline.", "target": { "name": "Order support", "location": "Confirm order node" }, "evidence_references": [] } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Finding not found (`finding_not_found`), or Findings is not enabled for this\nproject (`findings_not_enabled`). Read `code` to tell them apart.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "Finding not found in this project.", "code": "finding_not_found" } } } } } } }, "/findings/{finding_id}/evidence": { "get": { "tags": [ "Findings" ], "summary": "Get finding evidence", "description": "Returns the evidence behind a finding: daily history, source events, affected\nand comparison conversation IDs, co-occurring events, and the same data for any\ngrouped findings.\n\nEvidence is bounded to 100 source events, 50 affected conversations,\n20 comparison conversations, 20 co-occurring event types, and 25 grouped findings.\nThose budgets are shared across the finding and its grouped findings, not applied\nper finding. The `coverage` object reports what was returned against those limits.\n\nWhen evidence cannot be read for the finding's source, this still returns `200`\nwith an object carrying `error` instead of the evidence fields.\n", "operationId": "getFindingEvidence", "parameters": [ { "name": "finding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingEvidenceResponse" }, "example": { "data": { "finding": { "id": "8f14e45f-ceea-467a-9e1a-1b2c3d4e5f60", "source_type": "project_event", "source_key": "conversation.user_frustrated", "signal_name": "conversation.user_frustrated", "direction": "rising", "status": "open", "window_start_at": "2026-08-19T00:00:00.000000Z", "window_end_at": "2026-08-26T00:00:00.000000Z", "affected_count": 42, "baseline_count": 11, "current_rate": 0.18, "baseline_rate": 0.05, "last_observed_at": "2026-08-26T09:12:00.000000Z" }, "event_definition": { "id": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70819", "name": "conversation.user_frustrated", "display_name": "User frustrated", "description": "The user showed frustration during the conversation.", "property_schema": null }, "coverage": { "source_event_count": 128, "source_events_returned": 100, "affected_conversations_returned": 50, "comparison_conversations_returned": 20, "source_event_limit": 100, "affected_conversation_limit": 50, "comparison_conversation_limit": 20, "note": "Source events were truncated to the limit." }, "workflow": { "id": "c0ffee00-1111-4222-8333-444455556666", "name": "Order support" }, "daily_history": [ { "bucket_on": "2026-08-25", "event_count": 19, "conversation_count": 17 } ], "source_events": [ { "id": "7d1f0e2a-3b4c-4d5e-9f60-718293a4b5c6", "name": "conversation.user_frustrated", "occurred_at": "2026-08-25T14:02:00.000000Z", "conversation_id": "9e8d7c6b-5a49-4382-b1c0-fedcba987654", "properties": { "turn": 6 }, "whatsapp_config": { "id": "3c4d5e6f-7081-49a2-b3c4-d5e6f7081920", "kind": "whatsapp_cloud", "name": "Support line", "business_phone_number": "+16266694464", "meta_phone_number_id": "123456789012345" }, "source_workflow": { "workflow_id": "c0ffee00-1111-4222-8333-444455556666", "execution_id": "4d5e6f70-8192-4ab3-c4d5-e6f708192031", "snapshot_id": "5e6f7081-9203-4bc4-d5e6-f70819203142", "snapshot_version": 12, "test_mode": false } } ], "affected_conversation_ids": [ "9e8d7c6b-5a49-4382-b1c0-fedcba987654" ], "comparison_conversation_ids": [ "1f2e3d4c-5b6a-4798-8a90-0b1c2d3e4f50" ], "co_occurring_events": [ { "name": "conversation.handoff_requested", "event_count": 14 } ], "grouped_findings": [], "evidence_by_finding": [] } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Finding not found (`finding_not_found`), or Findings is not enabled for this\nproject (`findings_not_enabled`). Read `code` to tell them apart.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "Finding not found in this project.", "code": "finding_not_found" } } } } } } }, "/findings/{finding_id}/start_investigation": { "post": { "tags": [ "Findings" ], "summary": "Start an investigation", "description": "Queues a Kapso Agent Investigator run for the finding. The investigation is\nasynchronous; poll the finding to read the result.\n\nReturns `422` when the finding already has an active investigation, is not\ncurrently eligible for one, or the investigator is not configured for the project,\nand `409` when another dispatch is in flight.\n", "operationId": "startFindingInvestigation", "parameters": [ { "name": "finding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Investigation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingInvestigationAcceptedResponse" }, "example": { "data": { "finding_id": "8f14e45f-ceea-467a-9e1a-1b2c3d4e5f60", "investigation_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "status": "queued" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Finding not found (`finding_not_found`), or Findings is not enabled for this\nproject (`findings_not_enabled`). Read `code` to tell them apart.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "Finding not found in this project.", "code": "finding_not_found" } } } }, "409": { "description": "An investigation dispatch is already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" } } } }, "422": { "description": "Finding is not eligible for investigation, or the investigator is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "The Finding is already being investigated or is not currently eligible.", "code": "investigation_unavailable" } } } } } } }, "/findings/{finding_id}/dismiss": { "post": { "tags": [ "Findings" ], "summary": "Dismiss a finding", "description": "Removes the finding from the list. Both `reason` and `note` are required.\nA dismissed finding can reopen if monitoring detects the problem again, and it\nstays readable through `GET /findings/{finding_id}`.\n", "operationId": "dismissFinding", "parameters": [ { "name": "finding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason", "note" ], "properties": { "reason": { "type": "string", "enum": [ "not_relevant", "expected_behavior", "already_fixed", "incorrect", "other" ] }, "note": { "type": "string", "description": "Why the finding is being dismissed." } } }, "example": { "reason": "already_fixed", "note": "The workflow was corrected in release 2.4." } } } }, "responses": { "200": { "description": "Finding dismissed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingVerificationMutationResponse" }, "example": { "data": { "finding_id": "8f14e45f-ceea-467a-9e1a-1b2c3d4e5f60", "verification_id": "6f708192-0314-42d5-b6e7-f8091a2b3c4d", "status": "dismissed" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Finding not found (`finding_not_found`), or Findings is not enabled for this\nproject (`findings_not_enabled`). Read `code` to tell them apart.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "Finding not found in this project.", "code": "finding_not_found" } } } }, "422": { "description": "Missing or invalid `reason` or `note`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "param is missing or the value is empty: note" } } } } } } }, "/findings/{finding_id}/mark_addressed": { "post": { "tags": [ "Findings" ], "summary": "Mark a finding as addressed", "description": "Records the current metrics as a baseline and starts monitoring the finding.\nRequires a completed investigation that covers the finding's current evidence;\notherwise this returns `422`.\n", "operationId": "markFindingAddressed", "parameters": [ { "name": "finding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Monitoring started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingVerificationMutationResponse" }, "example": { "data": { "finding_id": "8f14e45f-ceea-467a-9e1a-1b2c3d4e5f60", "verification_id": "6f708192-0314-42d5-b6e7-f8091a2b3c4d", "status": "monitoring" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Finding not found (`finding_not_found`), or Findings is not enabled for this\nproject (`findings_not_enabled`). Read `code` to tell them apart.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "Finding not found in this project.", "code": "finding_not_found" } } } }, "422": { "description": "Finding has no completed investigation covering its current evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingsErrorResponse" }, "example": { "error": "Only completed investigations covering current evidence can be marked as addressed." } } } } } } }, "/notifications/events": { "get": { "tags": [ "Notifications" ], "summary": "List notification event types", "description": "The catalog of events you can route, ordered by category and name. Use `key` when\ncreating a route. Internal events such as the test notification are not listed.\n", "operationId": "listNotificationEventTypes", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationEventType" } } } }, "example": { "data": [ { "key": "findings.detected", "name": "New finding detected", "description": "When Kapso detects a new finding, not each refresh of its evidence.", "category": "findings", "severity": "warning", "supported_channels": [ "email", "slack" ], "data_contract": { "required": [], "optional": [ "title", "message", "resource_name", "details", "occurred_at" ] }, "surface_path_template": "/projects/%s/findings" } ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/notifications/destinations": { "get": { "tags": [ "Notifications" ], "summary": "List team destinations", "description": "Returns the project's shared email destinations and the Slack channel destinations\nconnected from the Kapso app, including `pending` and `unhealthy` ones. Removed\ndestinations and personal member destinations are never returned.\n", "operationId": "listNotificationDestinations", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationDestination" } } } }, "example": { "data": [ { "id": "6f708192-0314-42d5-b6e7-f8091a2b3c4d", "kind": "shared_email", "label": "Ops inbox", "status": "active", "channel": "email", "address": "ops@example.com", "verified_at": "2026-09-01T12:00:00.000000Z", "slack_channel_binding_id": null, "workspace_name": null, "user_id": null, "created_at": "2026-09-01T11:58:00.000000Z", "updated_at": "2026-09-01T12:00:00.000000Z" } ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "Notifications" ], "summary": "Create a shared email destination", "description": "Creates a `shared_email` destination with status `pending` and sends a verification\nemail to the address. The link expires after 7 days. The destination cannot receive\nnotifications until the recipient confirms. Addresses belonging to project members\nare rejected; those members manage their own personal notification preferences in\nthe Kapso app.\n\nSlack channels are added from the Kapso app under **Notifications**. Once connected\nthey appear in `GET /notifications/destinations` and can be routed like any other\ndestination. Requesting `kind: slack_channel` here returns `400`.\n\nCreating a destination for an address that was previously removed reuses the\nexisting destination: it returns to `pending` and a new verification email is sent.\n", "operationId": "createNotificationDestination", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "address" ], "properties": { "kind": { "type": "string", "enum": [ "shared_email" ] }, "address": { "type": "string", "description": "Email address." }, "label": { "type": "string", "description": "Display name for the destination. Optional." } } }, "example": { "kind": "shared_email", "address": "ops@example.com", "label": "Ops inbox" } } } }, "responses": { "201": { "description": "Destination created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NotificationDestination" } } }, "example": { "data": { "id": "6f708192-0314-42d5-b6e7-f8091a2b3c4d", "kind": "shared_email", "label": "Ops inbox", "status": "pending", "channel": "email", "address": "ops@example.com", "verified_at": null, "slack_channel_binding_id": null, "workspace_name": null, "user_id": null, "created_at": "2026-09-01T11:58:00.000000Z", "updated_at": "2026-09-01T11:58:00.000000Z" } } } } }, "400": { "description": "Unsupported destination kind", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Add Slack channels through the dashboard." } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "description": "Invalid destination", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "examples": { "member_address": { "value": { "errors": { "base": [ "This email belongs to a project member. Use a shared inbox for team alerts." ] } } }, "suppressed_address": { "value": { "errors": { "base": [ "This email address is blocked from receiving emails. Use a different shared inbox." ] } } } } } } } } } }, "/notifications/destinations/{destination_id}": { "delete": { "tags": [ "Notifications" ], "summary": "Remove a team destination", "description": "Disables a shared email or Slack channel destination, deletes its routes, and\ncancels its pending deliveries. The destination stops appearing in\n`GET /notifications/destinations`; its delivery history is kept. Personal member\ndestinations are not addressable and return `404`.\n", "operationId": "deleteNotificationDestination", "parameters": [ { "name": "destination_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Destination removed" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Destination not found in this project" } } } }, "/notifications/routes": { "get": { "tags": [ "Notifications" ], "summary": "List routes", "description": "Event types currently routed to team destinations, oldest first.", "operationId": "listNotificationRoutes", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationRoute" } } } }, "example": { "data": [ { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "destination_id": "6f708192-0314-42d5-b6e7-f8091a2b3c4d", "event_key": "findings.detected", "created_at": "2026-09-01T12:05:00.000000Z", "updated_at": "2026-09-01T12:05:00.000000Z" } ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "put": { "tags": [ "Notifications" ], "summary": "Create or update a route", "description": "Routes an event type to a team destination. Every event is delivered immediately.\nCalled again for the same `destination_id` and `event_key`, it returns the existing\nroute. The destination may be `pending`; deliveries start once it is `active`.\nUnknown event keys and internal events return `400`.\n", "operationId": "upsertNotificationRoute", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destination_id", "event_key" ], "properties": { "destination_id": { "type": "string", "format": "uuid" }, "event_key": { "type": "string", "description": "A `key` from `GET /notifications/events`." } } }, "example": { "destination_id": "6f708192-0314-42d5-b6e7-f8091a2b3c4d", "event_key": "findings.detected" } } } }, "responses": { "200": { "description": "Route saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NotificationRoute" } } }, "example": { "data": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "destination_id": "6f708192-0314-42d5-b6e7-f8091a2b3c4d", "event_key": "findings.detected", "created_at": "2026-09-01T12:05:00.000000Z", "updated_at": "2026-09-01T12:05:00.000000Z" } } } } }, "400": { "description": "Unknown or internal event key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "unknown": { "value": { "error": "Unknown notification event: findings.detectd" } }, "internal": { "value": { "error": "This notification event is not available through the Platform API." } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Destination not found in this project" }, "422": { "description": "Invalid route", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "example": { "errors": { "notification_destination": [ "must be a shared destination; personal emails follow each member's preferences" ] } } } } } } } }, "/notifications/routes/{id}": { "delete": { "tags": [ "Notifications" ], "summary": "Delete a route", "description": "Deletes the route and cancels its pending deliveries.", "operationId": "deleteNotificationRoute", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Route removed" }, "400": { "description": "The route belongs to an internal event and cannot be removed through the API" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Route not found in this project" } } } }, "/whatsapp/accounts/{waba_id}/funding": { "get": { "tags": [ "WhatsApp Funding" ], "summary": "Get WABA funding status", "description": "Returns the current Kapso funding evidence for a WhatsApp Business Account.\n\nReads persisted evidence only - no synchronous Meta request is made. `waba_id` is the\nMeta WABA ID, not a Kapso UUID. WABAs that are not visible to your project return 404.\n", "operationId": "getWhatsappAccountFunding", "parameters": [ { "name": "waba_id", "in": "path", "required": true, "description": "Meta WhatsApp Business Account ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Funding status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFundingResponse" }, "example": { "data": { "waba_id": "4188880514714289", "business_portfolio_id": "1991231921410797", "status": "not_funded", "reason": "existing_payment_method", "message": "Existing Meta payment method kept.", "currency": "USD", "waba_currency": "USD", "last_verified_at": null, "last_checked_at": "2026-09-13T02:45:00Z", "paid_messages": { "paused": false, "reasons": [] }, "operation": { "id": "ad0d68c2-3a0d-43d9-aa41-d7bd1bc6792b", "status": "succeeded", "started_at": "2026-09-13T02:44:00Z", "finished_at": "2026-09-13T02:45:00Z", "error_kind": null, "meta_error_code": null } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "tags": [ "WhatsApp Funding" ], "summary": "Ensure WABA funding", "description": "Verifies an external multi-partner solution account with Meta and ensures Kapso funding\nfor it, without waiting for the Meta association webhook. Use it after Embedded Signup\ncompletes.\n\nYour project must have exactly one active **external** multi-partner solution; you\ncannot select a solution or project, set the WABA currency, or supply a token. When the\nmembership is unknown, Kapso reads the WABA through that solution and verifies its owning\nportfolio before recording the association. Financial setup then runs in the background.\n\n`202` means a funding run is pending or running - it is **not** confirmation that the\naccount is funded. Poll `GET /whatsapp/accounts/{waba_id}/funding` until the run reaches\na terminal state and the funding `status` is `funded`. `200` is returned when the account\nis already funded or when no new run was started.\n\nIdempotent on desired state, with no `Idempotency-Key`: repeated calls reuse an\nin-progress run, and a terminal run is returned during a 30 second cooldown. After the\ncooldown a new run is started. The endpoint never resumes an explicitly disabled\nportfolio, a removed membership, or a revoked attachment - those stay explicit\nworkflows.\n", "operationId": "ensureWhatsappAccountFunding", "parameters": [ { "name": "waba_id", "in": "path", "required": true, "description": "Meta WhatsApp Business Account ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappEnsureFundingRequest" } } } }, "responses": { "200": { "description": "Already funded, or no new run was started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFundingResponse" } } } }, "202": { "description": "A funding run is pending or running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFundingResponse" }, "example": { "data": { "waba_id": "109537945127015", "business_portfolio_id": "823380597459265", "status": "not_funded", "reason": null, "message": "Kapso funding is not active.", "currency": "USD", "waba_currency": "USD", "last_verified_at": null, "last_checked_at": null, "paid_messages": { "paused": false, "reasons": [] }, "operation": { "id": "ad0d68c2-3a0d-43d9-aa41-d7bd1bc6792b", "status": "pending", "started_at": "2026-09-15T01:00:00Z", "finished_at": null, "error_kind": null, "meta_error_code": null } } } } } }, "400": { "description": "Missing or invalid `waba_id` or `business_portfolio_id`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "409": { "description": "Conflicting state: no single active external solution, funding disabled for the\nportfolio, the WABA belongs to another portfolio, project or solution, Meta did not\nconfirm the association, or the membership or attachment was removed and must be\nreconnected explicitly.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Meta could not verify account access. No local records are created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_kind": { "type": "string", "nullable": true }, "meta_error_code": { "type": "integer", "nullable": true }, "meta_trace_id": { "type": "string", "nullable": true } } }, "example": { "error": "Meta could not verify account access. Retry later or contact support.", "error_kind": "meta_unavailable", "meta_error_code": null, "meta_trace_id": null } } } }, "503": { "description": "Contention or queue unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/accounts/{waba_id}/usage": { "get": { "tags": [ "WhatsApp Funding" ], "summary": "Get WABA usage", "description": "Returns charges recorded for this project on one WABA, broken down by usage kind\n(currently messaging and calling).\n\nFree messages, unposted observations, and Meta charges paid outside Kapso are excluded.\nA zero total means zero recorded charges, not proof of zero spend.\n", "operationId": "getWhatsappAccountUsage", "parameters": [ { "name": "waba_id", "in": "path", "required": true, "description": "Meta WhatsApp Business Account ID.", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "required": true, "description": "Inclusive start of the window, ISO 8601 with an offset or `Z`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "required": true, "description": "Exclusive end of the window. At most 31 days after `start_time`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Recorded usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBillingUsageResponse" }, "example": { "data": { "start_time": "2026-09-12T00:00:00Z", "end_time": "2026-09-13T00:00:00Z", "time_basis": "recorded_at", "currency": "USD", "charge_scope": "kapso_recorded_charges", "totals": { "customer_charge_micro_usd": 115000 }, "breakdown": [ { "usage_kind": "messaging", "customer_charge_micro_usd": 90000, "billable_messages": 1, "sync": { "status": "delayed", "last_synced_at": "2026-09-12T23:30:00Z", "usage_through": "2026-09-12T23:25:00Z" } }, { "usage_kind": "calling", "customer_charge_micro_usd": 25000, "coverage": { "status": "supported", "reason": null }, "sync": { "status": "synced", "last_synced_at": null, "usage_through": "2026-09-13T00:00:00Z" } } ] } } } } }, "400": { "description": "Invalid or missing time range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Use ISO 8601 start_time and end_time, at most 31 days apart." } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/portfolios/{portfolio_id}/accounts": { "get": { "tags": [ "WhatsApp Funding" ], "summary": "List portfolio accounts with funding", "description": "Returns the WABAs in a Meta Business Portfolio that are visible to your project, each\nwith its funding status. Always cursor-paginated, ordered by creation time descending.\n\nA listed account is not necessarily funded or currently reachable in Meta - evidence is\nkept after disconnection.\n", "operationId": "listWhatsappPortfolioAccounts", "parameters": [ { "name": "portfolio_id", "in": "path", "required": true, "description": "Meta Business Portfolio ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "description": "Cursor for the next page. Pass `paging.next` unchanged.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Cursor for the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounts with funding status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFundingListResponse" } } } }, "400": { "description": "Invalid cursor or pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/portfolios/{portfolio_id}/usage": { "get": { "tags": [ "WhatsApp Funding" ], "summary": "Get portfolio usage", "description": "Returns charges recorded for this project across the portfolio's accounts, broken down\nby usage kind. Other partners' activity on the same portfolio is not included.\n", "operationId": "getWhatsappPortfolioUsage", "parameters": [ { "name": "portfolio_id", "in": "path", "required": true, "description": "Meta Business Portfolio ID.", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "required": true, "description": "Inclusive start of the window, ISO 8601 with an offset or `Z`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "required": true, "description": "Exclusive end of the window. At most 31 days after `start_time`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Recorded usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBillingUsageResponse" } } } }, "400": { "description": "Invalid or missing time range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/whatsapp/portfolios/{portfolio_id}/funding/revoke": { "post": { "tags": [ "WhatsApp Funding" ], "summary": "Stop portfolio funding", "description": "Queues an asynchronous stop of Kapso funding for a Meta Business Portfolio. No request\nbody is required.\n\nDisables portfolio auto-funding and revokes each approved allocation in the validated\nscope, so **every WABA using that allocation is affected**. A `202` is acceptance, not\nconfirmation that Meta funding stopped - poll the operation endpoint until `succeeded`\nor `failed`.\n\nRevoking funding does not disconnect numbers, remove a partner, erase billing history,\nor forgive outstanding usage. Customers may need their own Meta payment method\nafterwards.\n", "operationId": "revokeWhatsappPortfolioFunding", "parameters": [ { "name": "portfolio_id", "in": "path", "required": true, "description": "Meta Business Portfolio ID.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable unique key of 1-255 bytes per logical request. Reuse it when retrying after a network failure - the original operation is returned. Reusing a key for a different portfolio returns 409.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Revocation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFundingOperationResponse" }, "example": { "data": { "operation_id": "2a2c446c-87c2-4f8a-ae74-aef1819e03f5", "business_portfolio_id": "30458864570425307", "status": "queued", "requested_at": "2026-09-13T02:45:00Z", "message": "Portfolio funding revocation is queued." } } } } }, "400": { "description": "Missing or oversized Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "An Idempotency-Key header of 1 to 255 bytes is required." } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The Idempotency-Key was used for another portfolio, or the scope is unsafe", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "This Idempotency-Key was used for another portfolio." } } } }, "503": { "description": "Revocation queue unavailable, retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/whatsapp/portfolios/{portfolio_id}/funding/operations/{operation_id}": { "get": { "tags": [ "WhatsApp Funding" ], "summary": "Get funding operation", "description": "Returns the status of a revocation operation. Readable after the WABA moves or is\ndisconnected. A `failed` operation can be partially completed - inspect WABA funding\nand contact support before starting a new one.\n", "operationId": "getWhatsappPortfolioFundingOperation", "parameters": [ { "name": "portfolio_id", "in": "path", "required": true, "description": "Meta Business Portfolio ID.", "schema": { "type": "string" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFundingOperationResponse" }, "example": { "data": { "operation_id": "2a2c446c-87c2-4f8a-ae74-aef1819e03f5", "business_portfolio_id": "30458864570425307", "status": "succeeded", "requested_at": "2026-09-13T02:45:00Z", "message": "Portfolio funding has been stopped." } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } } } }