{"openapi":"3.1.0","info":{"title":"Kirimdev Public API","version":"1.0.0","description":"Self-service REST API for sending WhatsApp messages, subscribing to events, and managing your inbox programmatically. See docs.kirimdev.com for guides and reference.","contact":{"name":"Kirimdev Support","url":"https://kirimdev.com"}},"servers":[{"url":"https://api.kirimdev.com/v1","description":"Production"}],"tags":[{"name":"Meta","description":"Liveness probe and API-key introspection."},{"name":"Accounts","description":"Inspect the WhatsApp accounts connected to your organization. Each account exposes its Meta `business_phone_number_id` — the value used in `/{phone_number_id}/...` paths to address it (Meta-style)."},{"name":"Messages","description":"Send and read WhatsApp messages across every supported content type."},{"name":"Templates","description":"List and inspect Meta-approved templates synced to your Kirimdev org."},{"name":"Conversations","description":"Inspect chats, change assignment and status, attach labels."},{"name":"Contacts","description":"CRUD over the people you exchange messages with, plus label attach + bulk-tag."},{"name":"Labels","description":"Coloured tags for contacts and conversations. Team-scoped per Kirimdev's internal model."},{"name":"Customers","description":"End-customers (tenant-of-tenant) — your platform's own clients. Each Customer can connect their own WhatsApp accounts via setup links and you send messages on their behalf. Distinct from `Contacts`."},{"name":"Webhook Subscriptions","description":"Subscribe to events, rotate signing secrets, pause/resume delivery."},{"name":"Webhook Deliveries","description":"Dead-letter queue + replay surface for outbound webhook failures."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Kirimdev Public API key. Format: `kdv_live_<24-char base64url>`. Issue keys in Settings → API Keys."}},"schemas":{"ApiErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"invalid_request_error"},"code":{"type":"string","example":"invalid_phone_number"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string","example":"req_01HXYZABCDEFGHJKMNPQRSTVWX"}},"required":["type","code","message","request_id"]}},"required":["error"]},"WhatsappAccountEmbedded":{"type":"object","properties":{"phone_number":{"type":["string","null"]},"phone_number_id":{"type":["string","null"],"example":"106540352242922","description":"Meta `business_phone_number_id` — use as the `{phone_number_id}` path segment in `/v1/{phone_number_id}/...` endpoints."},"customer":{"type":["object","null"],"properties":{"id":{"type":"string","example":"cus_01HXYZABCDEFGHJKMNPQRSTVWX"},"name":{"type":"string"}},"required":["id","name"],"description":"End-customer (multi-tenant platform mode) that owns this account. NULL for direct-org accounts."}},"required":["phone_number","phone_number_id","customer"]},"Message":{"type":"object","properties":{"id":{"type":"string","example":"msg_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["message"]},"to":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","pending","sent","delivered","read","failed"]},"created_at":{"type":"string","format":"date-time"},"conversation_id":{"type":"string"},"message_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable Kirim error code. Known values include `outside_24h_window`, `marketing_opted_out`, `marketing_blocked_by_user`, `recipient_unavailable`, `unsupported_message_type`, `account_restricted`, `account_locked`, `consent_required`, `customer_suspended`, `permission_revoked`, `auth_expired`, `app_rate_limited`, `account_rate_limited`, `template_not_found`, `template_paused`, `template_policy_violation`, `flow_blocked`, `media_upload_failed`, `media_download_failed`, `undeliverable`, `policy_violation`, `upstream_error`."},"message":{"type":"string"},"provider_code":{"type":["number","null"]}},"required":["code","message","provider_code"]}},"required":["id","object","status"]},"Template":{"type":"object","properties":{"id":{"type":"string","example":"tmpl_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["template"]},"name":{"type":"string"},"language":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected"]},"content":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"components":{},"whatsapp_account":{"$ref":"#/components/schemas/WhatsappAccountEmbedded"},"provider_template_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","name","language","status","content","variables","whatsapp_account","provider_template_id","created_at","updated_at"]},"Account":{"type":"object","properties":{"object":{"type":"string","enum":["account"]},"phone_number_id":{"type":["string","null"],"example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id`. Use as the `{phone_number_id}` path parameter in `/v1/{phone_number_id}/...` endpoints. Nullable while onboarding is in flight."},"phone_number":{"type":["string","null"],"example":"+628111222333"},"name":{"type":["string","null"],"example":"Customer Support"},"status":{"type":"string","example":"connected","description":"Lifecycle state of the account (e.g. `connected`, `disconnected`, `degraded`, `onboarding`)."},"customer_id":{"type":["string","null"],"example":"cus_01HXYZABCDEFGHJKMNPQRSTVWX","description":"Public id of the end-customer (multi-tenant platform mode) that owns this account. NULL for direct-org accounts. Filter the list endpoint via `?customer_id=cus_...`."}},"required":["object","phone_number_id","phone_number","name","status","customer_id"]},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string","example":"wbs_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["webhook_subscription"]},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","paused","disabled"]},"disabled_reason":{"type":["string","null"]},"consecutive_failures":{"type":"integer","minimum":0},"secrets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"sec_01HXYZABCDEFGHJKMNPQRSTVWX"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}},"required":["id","created_at","expires_at"]}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"initial_secret":{"type":"string"}},"required":["id","object","url","description","events","status","disabled_reason","consecutive_failures","secrets","created_at","updated_at"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","example":"wbd_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["webhook_delivery"]},"subscription_id":{"type":"string"},"event_type":{"type":"string"},"event_id":{"type":"string"},"status":{"type":"string","enum":["pending","succeeded","failed","dead"]},"attempt_count":{"type":"integer","minimum":0},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"response_status":{"type":["integer","null"]},"response_body_snippet":{"type":["string","null"]},"duration_ms":{"type":["integer","null"]},"replayed_from":{"type":["string","null"]},"payload":{},"created_at":{"type":"string","format":"date-time"}},"required":["id","object","subscription_id","event_type","event_id","status","attempt_count","last_attempt_at","next_attempt_at","response_status","response_body_snippet","duration_ms","replayed_from","created_at"]},"Conversation":{"type":"object","properties":{"id":{"type":"string","example":"cnv_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["conversation"]},"status":{"type":"string","enum":["open","resolved","pending"]},"contact":{"type":"object","properties":{"id":{"type":"string"},"phone_number":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","phone_number","name"]},"whatsapp_account":{"$ref":"#/components/schemas/WhatsappAccountEmbedded"},"assignee":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","name","email"]},"unread_count":{"type":"integer","minimum":0},"last_message_at":{"type":["string","null"],"format":"date-time"},"last_inbound_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","status","contact","whatsapp_account","assignee","unread_count","last_message_at","last_inbound_at","created_at","updated_at"]},"Contact":{"type":"object","properties":{"id":{"type":"string","example":"ctc_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["contact"]},"phone_number":{"type":["string","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{}},"whatsapp_account":{"$ref":"#/components/schemas/WhatsappAccountEmbedded"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","phone_number","name","email","metadata","whatsapp_account","created_at","updated_at"]},"Label":{"type":"object","properties":{"id":{"type":"string","example":"lbl_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["label"]},"name":{"type":"string"},"color":{"type":"string","enum":["gray","red","orange","amber","yellow","lime","green","emerald","teal","sky","blue","violet","pink"]},"team_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","name","color","team_id","created_at","updated_at"]},"Customer":{"type":"object","properties":{"id":{"type":"string","example":"cus_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["customer"]},"name":{"type":"string"},"email":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","suspended","archived"]},"metadata":{"type":["object","null"],"additionalProperties":{}},"archived_at":{"type":["string","null"],"format":"date-time"},"team_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","name","email","status","metadata","archived_at","team_id","created_at","updated_at"]},"CustomerSetupLink":{"type":"object","properties":{"id":{"type":"string","example":"csl_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["customer_setup_link"]},"customer_id":{"type":"string"},"status":{"type":"string","enum":["active","consumed","expired","revoked"]},"token_last4":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"consumed_at":{"type":["string","null"],"format":"date-time"},"success_redirect_url":{"type":["string","null"],"format":"uri","description":"Where the tenant is redirected after successful Embedded Signup. We append `?customer_id=&account_id=&status=success` on the redirect."},"failure_redirect_url":{"type":["string","null"],"format":"uri","description":"Where the tenant is redirected on failure (link error, Meta signup cancelled, etc.). We append `?customer_id=&status=failed&reason=<code>`."},"created_at":{"type":"string","format":"date-time"}},"required":["id","object","customer_id","status","token_last4","expires_at","consumed_at","success_redirect_url","failure_redirect_url","created_at"]},"CustomerSetupLinkWithToken":{"allOf":[{"$ref":"#/components/schemas/CustomerSetupLink"},{"type":"object","properties":{"setup_url":{"type":"string","format":"uri"}},"required":["setup_url"]}]},"MessageListItem":{"type":"object","properties":{"id":{"type":"string","example":"msg_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["message"]},"conversation_id":{"type":"string"},"to":{"type":["string","null"]},"direction":{"type":"string","enum":["inbound","outbound"]},"type":{"type":"string"},"content":{"type":["string","null"]},"media_url":{"type":["string","null"]},"status":{"type":"string","enum":["pending","sent","delivered","read","failed"]},"created_at":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable Kirim error code. Known values include `outside_24h_window`, `marketing_opted_out`, `marketing_blocked_by_user`, `recipient_unavailable`, `unsupported_message_type`, `account_restricted`, `account_locked`, `consent_required`, `customer_suspended`, `permission_revoked`, `auth_expired`, `app_rate_limited`, `account_rate_limited`, `template_not_found`, `template_paused`, `template_policy_violation`, `flow_blocked`, `media_upload_failed`, `media_download_failed`, `undeliverable`, `policy_violation`, `upstream_error`."},"message":{"type":"string"},"provider_code":{"type":["number","null"]}},"required":["code","message","provider_code"]}},"required":["id","object","conversation_id","to","direction","type","content","media_url","status","created_at"]},"MeResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string","example":"org_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["organization"]},"name":{"type":"string"}},"required":["id","object","name"]},"api_key":{"type":"object","properties":{"id":{"type":"string","example":"key_01HXYZABCDEFGHJKMNPQRSTVWX"},"object":{"type":"string","enum":["api_key"]},"label":{"type":"string"},"last4":{"type":"string"}},"required":["id","object","label","last4"]},"rate_limits":{"type":"object","properties":{"tier":{"type":"string"},"write_per_minute":{"type":"integer"},"read_per_minute":{"type":"integer"}},"required":["tier","write_per_minute","read_per_minute"]}},"required":["organization","api_key","rate_limits"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListAccountsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Account"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"SendMessageResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"},"request_id":{"type":"string"}},"required":["data","request_id"]},"GetMessageResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListTemplatesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"GetTemplateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Template"},"request_id":{"type":"string"}},"required":["data","request_id"]},"SyncTemplatesResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","enum":["template_sync_result"]},"synced":{"type":"integer","example":12},"created":{"type":"integer","example":2},"updated":{"type":"integer","example":10}},"required":["object","synced","created","updated"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"CreateWebhookSubscriptionResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListWebhookSubscriptionsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"GetWebhookSubscriptionResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"request_id":{"type":"string"}},"required":["data","request_id"]},"UpdateWebhookSubscriptionResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"request_id":{"type":"string"}},"required":["data","request_id"]},"DeleteWebhookSubscriptionResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"AddWebhookSecretResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_secret"]},"secret":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}},"required":["id","object","secret","created_at","expires_at"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"DeleteWebhookSecretResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListWebhookDeliveriesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"GetWebhookDeliveryResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookDelivery"},"request_id":{"type":"string"}},"required":["data","request_id"]},"ReplayWebhookDeliveryResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_delivery"]},"replayed_from":{"type":"string"},"status":{"type":"string","enum":["pending"]}},"required":["id","object","replayed_from","status"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"BulkReplayResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"enqueued":{"type":"integer","minimum":0},"capped":{"type":"boolean"}},"required":["enqueued","capped"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListConversationsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"GetConversationResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListContactsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"GetContactResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListMessagesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MessageListItem"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"CreateContactResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"},"request_id":{"type":"string"}},"required":["data","request_id"]},"UpdateContactResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"},"request_id":{"type":"string"}},"required":["data","request_id"]},"DeleteContactResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["contact"]},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"AttachContactLabelResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"contact_id":{"type":"string"},"label_id":{"type":"string"},"attached":{"type":"boolean","enum":[true]}},"required":["contact_id","label_id","attached"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"DetachContactLabelResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"contact_id":{"type":"string"},"label_id":{"type":"string"},"attached":{"type":"boolean","enum":[false]}},"required":["contact_id","label_id","attached"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"BulkLabelContactsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"applied":{"type":"integer","minimum":0},"skipped_cross_org":{"type":"integer","minimum":0},"skipped_team_mismatch":{"type":"integer","minimum":0}},"required":["applied","skipped_cross_org","skipped_team_mismatch"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"UpdateConversationResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"},"request_id":{"type":"string"}},"required":["data","request_id"]},"AttachConversationLabelResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation_id":{"type":"string"},"label_id":{"type":"string"},"attached":{"type":"boolean","enum":[true]}},"required":["conversation_id","label_id","attached"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"DetachConversationLabelResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation_id":{"type":"string"},"label_id":{"type":"string"},"attached":{"type":"boolean","enum":[false]}},"required":["conversation_id","label_id","attached"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListLabelsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"CreateLabelResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Label"},"request_id":{"type":"string"}},"required":["data","request_id"]},"GetLabelResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Label"},"request_id":{"type":"string"}},"required":["data","request_id"]},"UpdateLabelResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Label"},"request_id":{"type":"string"}},"required":["data","request_id"]},"DeleteLabelResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["label"]},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListCustomersResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"CreateCustomerResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"},"request_id":{"type":"string"}},"required":["data","request_id"]},"GetCustomerResponse":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Customer"},{"type":"object","properties":{"whatsapp_accounts":{"type":"array","items":{"type":"object","properties":{"phone_number_id":{"type":["string","null"]},"phone_number":{"type":["string","null"]},"name":{"type":["string","null"]},"status":{"type":"string"},"onboarded_at":{"type":["string","null"],"format":"date-time"}},"required":["phone_number_id","phone_number","name","status","onboarded_at"]},"description":"WhatsApp accounts currently assigned to this customer."}},"required":["whatsapp_accounts"]}]},"request_id":{"type":"string"}},"required":["data","request_id"]},"UpdateCustomerResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"},"request_id":{"type":"string"}},"required":["data","request_id"]},"ArchiveCustomerResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["customer"]},"archived":{"type":"boolean","enum":[true]}},"required":["id","object","archived"]},"request_id":{"type":"string"}},"required":["data","request_id"]},"ListCustomerSetupLinksResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerSetupLink"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["data","has_more","next_cursor","request_id"]},"CreateCustomerSetupLinkResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerSetupLinkWithToken"},"request_id":{"type":"string"}},"required":["data","request_id"]},"UpdateCustomerSetupLinkResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerSetupLink"},"request_id":{"type":"string"}},"required":["data","request_id"]},"RevokeCustomerSetupLinkResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["customer_setup_link"]},"revoked":{"type":"boolean","enum":[true]},"status":{"type":"string","enum":["active","consumed","expired","revoked"]}},"required":["id","object","revoked","status"]},"request_id":{"type":"string"}},"required":["data","request_id"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["Meta"],"summary":"Liveness probe","description":"Unauthenticated health check. Returns 200 if the API is up.","responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]},"request_id":{"type":"string"}},"required":["data","request_id"]}}}}}}},"/me":{"get":{"tags":["Meta"],"summary":"Introspect the calling API key","description":"Returns the organization, API key, and rate-limit tier associated with the bearer token. Use to verify key validity from automation scripts.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"API key context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/accounts":{"get":{"tags":["Accounts"],"summary":"List connected WhatsApp accounts","description":"List the WhatsApp accounts attached to the calling organization. The returned `business_phone_number_id` is the value to use in `/{phone_number_id}/...` path-based endpoints (Meta-style — sender comes from the URL, not the body). Defaults to `status=connected` because that's the only state in which sends are accepted; pass `status=all` to inspect onboarding-in-progress or disconnected accounts. Response is intentionally not paginated.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["connected","all"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","pattern":"^cus_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"customer_id","in":"query"}],"responses":{"200":{"description":"Account list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAccountsResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/messages":{"post":{"tags":["Messages"],"summary":"Send a WhatsApp message or mark inbound as read","description":"Meta-style messages endpoint. Two operations share the same path, distinguished by the request body:\n\n**Outbound send** — body has a `type` field (`text`, `image`, `document`, `video`, `audio`, `template`, `interactive`). Body shape mirrors the Meta WhatsApp Cloud API; media variants accept either `link` (hosted URL) or `id` (Meta uploaded media). The sender is the WhatsApp account identified by `phone_number_id` in the URL path; there is no `from` field in the body. Pass `Idempotency-Key` to safely retry on network failure.\n\n**Read receipt** — body has `status: \"read\"` + `message_id` (the inbound wamid from your webhook). Sends a read receipt back to the sender so the double-tick turns blue on their phone. Optional `typing_indicator: { type: \"text\" }` shows a typing bubble alongside the receipt; Meta auto-dismisses after ~25 seconds or on first outbound message.\n\n**Pre-send validation** — the API performs compliance checks before queuing the send. A 422 response with `error.code` set to `marketing_opted_out` indicates the recipient has stopped marketing messages from your business (the customer did this via the WhatsApp app menu — webhook `user_preferences` notifies you of the change). `account_restricted` indicates Meta has restricted your WhatsApp account; check the account status via the dashboard. `consent_required` indicates the recipient has not opted in. `customer_suspended` indicates the operator has suspended (or archived) the customer that owns this WhatsApp account; sends are blocked until the customer is unsuspended via the dashboard. `upstream_error` indicates the WhatsApp account is disconnected. None of these are retryable until the underlying condition changes.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","description":"Optional idempotency token. See /docs/idempotency."},"required":false,"description":"Optional idempotency token. See /docs/idempotency.","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"recipient_type":{"type":"string","enum":["individual"]},"to":{"type":"string"},"type":{"type":"string","enum":["text"]},"text":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4096},"preview_url":{"type":"boolean"}},"required":["body"]}},"required":["messaging_product","to","type","text"],"title":"Text"},{"type":"object","properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"recipient_type":{"type":"string","enum":["individual"]},"to":{"type":"string"},"type":{"type":"string","enum":["image"]},"image":{"type":"object","properties":{"link":{"type":"string","format":"uri"},"id":{"type":"string","minLength":1,"maxLength":255},"caption":{"type":"string","maxLength":1024},"filename":{"type":"string","maxLength":255}}}},"required":["messaging_product","to","type","image"],"title":"Image"},{"type":"object","properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"recipient_type":{"type":"string","enum":["individual"]},"to":{"type":"string"},"type":{"type":"string","enum":["document"]},"document":{"type":"object","properties":{"link":{"type":"string","format":"uri"},"id":{"type":"string","minLength":1,"maxLength":255},"caption":{"type":"string","maxLength":1024},"filename":{"type":"string","maxLength":255}}}},"required":["messaging_product","to","type","document"],"title":"Document"},{"type":"object","properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"recipient_type":{"type":"string","enum":["individual"]},"to":{"type":"string"},"type":{"type":"string","enum":["video"]},"video":{"type":"object","properties":{"link":{"type":"string","format":"uri"},"id":{"type":"string","minLength":1,"maxLength":255},"caption":{"type":"string","maxLength":1024},"filename":{"type":"string","maxLength":255}}}},"required":["messaging_product","to","type","video"],"title":"Video"},{"type":"object","properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"recipient_type":{"type":"string","enum":["individual"]},"to":{"type":"string"},"type":{"type":"string","enum":["audio"]},"audio":{"type":"object","properties":{"link":{"type":"string","format":"uri"},"id":{"type":"string","minLength":1,"maxLength":255},"caption":{"type":"string","maxLength":1024},"filename":{"type":"string","maxLength":255},"voice":{"type":"boolean"}}}},"required":["messaging_product","to","type","audio"],"title":"Audio"},{"type":"object","properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"recipient_type":{"type":"string","enum":["individual"]},"to":{"type":"string"},"type":{"type":"string","enum":["template"]},"template":{"type":"object","properties":{"name":{"type":"string","minLength":1},"language":{"anyOf":[{"type":"string","minLength":2,"maxLength":15,"title":"Language code"},{"type":"object","properties":{"code":{"type":"string","minLength":2,"maxLength":15},"policy":{"type":"string"}},"required":["code"],"title":"Language object"}]},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["header","body","button"]},"sub_type":{"type":"string","enum":["url","quick_reply","copy_code","flow"]},"index":{"type":"integer","minimum":0},"parameters":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["type"],"additionalProperties":{}}}},"required":["name","language"]}},"required":["messaging_product","to","type","template"],"title":"Template"},{"type":"object","properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"recipient_type":{"type":"string","enum":["individual"]},"to":{"type":"string"},"type":{"type":"string","enum":["interactive"]},"interactive":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["cta_url"]},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"]},"action":{"type":"object","properties":{"name":{"type":"string","enum":["cta_url"]},"parameters":{"type":"object","properties":{"display_text":{"type":"string","minLength":1,"maxLength":20},"url":{"type":"string","format":"uri"}},"required":["display_text","url"]}},"required":["name","parameters"]}},"required":["type","body","action"],"title":"CTA URL"},{"type":"object","properties":{"type":{"type":"string","enum":["list"]},"header":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string","minLength":1,"maxLength":60}},"required":["type","text"]},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"]},"footer":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60}},"required":["text"]},"action":{"type":"object","properties":{"button":{"type":"string","minLength":1,"maxLength":20},"sections":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","maxLength":24},"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"title":{"type":"string","minLength":1,"maxLength":24},"description":{"type":"string","maxLength":72}},"required":["id","title"]},"minItems":1}},"required":["rows"]},"minItems":1}},"required":["button","sections"]}},"required":["type","body","action"],"title":"List"},{"type":"object","properties":{"type":{"type":"string","enum":["carousel"]},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"]},"action":{"type":"object","properties":{"cards":{"type":"array","items":{"type":"object","properties":{"card_index":{"type":"integer","minimum":0},"type":{"type":"string","enum":["cta_url"]},"header":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"image":{"type":"object","properties":{"link":{"type":"string","format":"uri"}},"required":["link"]}},"required":["type","image"],"title":"Image header"},{"type":"object","properties":{"type":{"type":"string","enum":["video"]},"video":{"type":"object","properties":{"link":{"type":"string","format":"uri"}},"required":["link"]}},"required":["type","video"],"title":"Video header"}]},"body":{"type":"object","properties":{"text":{"type":"string","maxLength":160}},"required":["text"]},"action":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","enum":["cta_url"]},"parameters":{"type":"object","properties":{"display_text":{"type":"string","minLength":1,"maxLength":20},"url":{"type":"string","format":"uri"}},"required":["display_text","url"]}},"required":["name","parameters"],"title":"CTA URL action"},{"type":"object","properties":{"buttons":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["quick_reply"]},"quick_reply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","minLength":1,"maxLength":20}},"required":["id","title"]}},"required":["type","quick_reply"]},"minItems":1}},"required":["buttons"],"title":"Quick-reply buttons"}]}},"required":["header","action"]},"minItems":2,"maxItems":10}},"required":["cards"]}},"required":["type","body","action"],"title":"Carousel"},{"type":"object","properties":{"type":{"type":"string","enum":["reply_buttons"]},"header":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string","minLength":1,"maxLength":60}},"required":["type","text"],"title":"Text header"},{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"image":{"type":"object","properties":{"link":{"type":"string","format":"uri"}},"required":["link"]}},"required":["type","image"],"title":"Image header"},{"type":"object","properties":{"type":{"type":"string","enum":["video"]},"video":{"type":"object","properties":{"link":{"type":"string","format":"uri"}},"required":["link"]}},"required":["type","video"],"title":"Video header"},{"type":"object","properties":{"type":{"type":"string","enum":["document"]},"document":{"type":"object","properties":{"link":{"type":"string","format":"uri"}},"required":["link"]}},"required":["type","document"],"title":"Document header"}]},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"]},"footer":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60}},"required":["text"]},"action":{"type":"object","properties":{"buttons":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["reply"]},"reply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","minLength":1,"maxLength":20}},"required":["id","title"]}},"required":["type","reply"]},"minItems":1,"maxItems":3}},"required":["buttons"]}},"required":["type","body","action"],"title":"Reply buttons"}]}},"required":["messaging_product","to","type","interactive"],"title":"Interactive"},{"type":"object","properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"status":{"type":"string","enum":["read"]},"message_id":{"type":"string","minLength":1,"description":"Meta WhatsApp message id (wamid) of the inbound message to mark as read. Get it from the inbound webhook payload — NOT a Kirim `msg_*` external id.","example":"wamid.HBgNNjI4MTIzNDU2Nzg5FQIAEhggMUE5MDM1QzVDMUYxQTAyRkVCNzZDQjVDMjFFRDQzNTUA"},"typing_indicator":{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"description":"Optional. When present, Meta also shows a typing indicator to the recipient that auto-dismisses on response or after ~25 seconds. Only include if you intend to respond — leaving the indicator hanging produces a poor UX."}},"required":["messaging_product","status","message_id"],"title":"Read receipt"}]}}}},"responses":{"200":{"description":"Message accepted for delivery, or read receipt sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"Upstream WhatsApp error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"tags":["Messages"],"summary":"List messages","description":"List messages for the WhatsApp account identified by `phone_number_id`. Filter by `conversation_id`, `direction`, `status`, or a `created_after`/`created_before` window.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^cnv_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"conversation_id","in":"query"},{"schema":{"type":"string","enum":["inbound","outbound"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string","enum":["pending","sent","delivered","read","failed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"created_after","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"created_before","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Message list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMessagesResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/messages/{id}":{"get":{"tags":["Messages"],"summary":"Fetch a sent message by id","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^msg_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Message resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMessageResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/templates":{"get":{"tags":["Templates"],"summary":"List approved templates","description":"List templates synced from Meta for the WhatsApp account identified by `phone_number_id`. Default filter is `status=approved`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","enum":["approved","pending","rejected","all"],"default":"approved"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":15},"required":false,"name":"language","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Template list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTemplatesResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/templates/{name}":{"get":{"tags":["Templates"],"summary":"Fetch a single template by name","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":512},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","minLength":2,"maxLength":15},"required":false,"name":"language","in":"query"}],"responses":{"200":{"description":"Template resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTemplateResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/templates/sync":{"post":{"tags":["Templates"],"summary":"Sync templates from Meta","description":"Pull the latest template inventory from Meta and upsert into the Kirim DB for this WhatsApp account. Idempotent — call any time, returns a `{ created, updated, synced }` summary. Useful for platform integrations (multi-tenant Customers) so they don't need to wait for an operator to click \"Sync\" in the dashboard.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"}],"responses":{"200":{"description":"Sync summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncTemplatesResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"Upstream WhatsApp error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/webhook_subscriptions":{"post":{"tags":["Webhook Subscriptions"],"summary":"Create a webhook subscription","description":"Create a webhook subscription. The response carries `initial_secret` ONCE — store it server-side immediately; Kirimdev cannot show it again.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":200},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.status","conversation.assigned","conversation.closed","contact.created","contact.updated","customer.created","customer.updated","customer.archived","customer.onboarded","customer.setup_link.created","customer.setup_link.consumed"]},"minItems":1}},"required":["url","events"]}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscriptionResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"tags":["Webhook Subscriptions"],"summary":"List webhook subscriptions","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["active","paused","disabled","all"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Subscription list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWebhookSubscriptionsResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/webhook_subscriptions/{id}":{"get":{"tags":["Webhook Subscriptions"],"summary":"Fetch one webhook subscription","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^wbs_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Subscription resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetWebhookSubscriptionResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"tags":["Webhook Subscriptions"],"summary":"Update a webhook subscription","description":"Toggle status (active/paused), update URL/events/description.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^wbs_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":["string","null"],"maxLength":200},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.status","conversation.assigned","conversation.closed","contact.created","contact.updated","customer.created","customer.updated","customer.archived","customer.onboarded","customer.setup_link.created","customer.setup_link.consumed"]},"minItems":1},"status":{"type":"string","enum":["active","paused"]}}}}}},"responses":{"200":{"description":"Updated subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookSubscriptionResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"delete":{"tags":["Webhook Subscriptions"],"summary":"Delete a webhook subscription","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^wbs_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWebhookSubscriptionResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/webhook_subscriptions/{id}/secrets":{"post":{"tags":["Webhook Subscriptions"],"summary":"Add a new signing secret (rotation)","description":"Issue a new signing secret with the given expiry. During the overlap window every active secret is used to sign outbound deliveries; subscribers verify against any of them.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^wbs_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in_hours":{"type":"integer","minimum":1,"maximum":336}}}}}},"responses":{"200":{"description":"New secret created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddWebhookSecretResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Conflict (e.g. webhook subscription disabled, setup link inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/webhook_subscriptions/{id}/secrets/{secret_id}":{"delete":{"tags":["Webhook Subscriptions"],"summary":"Revoke a signing secret","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^wbs_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^sec_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"secret_id","in":"path"}],"responses":{"200":{"description":"Secret revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWebhookSecretResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/webhook_deliveries":{"get":{"tags":["Webhook Deliveries"],"summary":"List webhook deliveries","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^wbs_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"subscription_id","in":"query"},{"schema":{"type":"string","enum":["pending","succeeded","failed","dead"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"event_type","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"created_after","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"created_before","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Delivery list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWebhookDeliveriesResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/webhook_deliveries/{id}":{"get":{"tags":["Webhook Deliveries"],"summary":"Fetch one delivery (with full payload)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^wbd_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Delivery resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetWebhookDeliveryResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/webhook_deliveries/{id}/replay":{"post":{"tags":["Webhook Deliveries"],"summary":"Replay a single delivery","description":"Re-fire a single delivery against the original subscription URL. Creates a fresh delivery row; the original stays for audit.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^wbd_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Replay enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayWebhookDeliveryResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Conflict (e.g. webhook subscription disabled, setup link inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/webhook_deliveries/bulk_replay":{"post":{"tags":["Webhook Deliveries"],"summary":"Replay deliveries in bulk (DLQ)","description":"Replay every delivery for a subscription matching the filter, capped at 1000 per request. Paginate via `created_after` / `created_before` for larger backfills.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","pattern":"^wbs_[0-9A-HJKMNP-TV-Z]{26}$"},"status":{"type":"string","enum":["failed","dead"],"default":"dead"},"event_type":{"type":"string","minLength":1,"maxLength":64},"created_after":{"type":"string","format":"date-time"},"created_before":{"type":"string","format":"date-time"}},"required":["subscription_id"]}}}},"responses":{"200":{"description":"Bulk replay enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReplayResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Conflict (e.g. webhook subscription disabled, setup link inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","description":"List conversations for the WhatsApp account identified by `phone_number_id`. Ordered newest-active first by `last_message_at` (NULLS LAST).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","enum":["open","resolved","pending"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","pattern":"^ctc_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"contact_id","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Conversation list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListConversationsResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/conversations/{id}":{"get":{"tags":["Conversations"],"summary":"Fetch a conversation by id","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^cnv_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Conversation resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetConversationResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"tags":["Conversations"],"summary":"Update a conversation","description":"Update status (`open` / `resolved` / `pending`) and/or `assigned_to` (user id, or `null` to clear). At least one field must be present.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^cnv_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","resolved","pending"]},"assigned_to":{"type":["string","null"],"minLength":1,"maxLength":64}}}}}},"responses":{"200":{"description":"Updated conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConversationResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","description":"List contacts attached to the WhatsApp account identified by `phone_number_id`. Filter by exact `phone` (E.164) or partial `search` (matches name and email).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"phone","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Contact list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListContactsResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"tags":["Contacts"],"summary":"Create a contact","description":"Create a contact attached to the WhatsApp account identified by `phone_number_id` in the URL path.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":["string","null"],"maxLength":255,"format":"email"},"metadata":{"type":"object","additionalProperties":{}}},"required":["phone_number"]}}}},"responses":{"200":{"description":"Contact created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Fetch a contact by id","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^ctc_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Contact resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetContactResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"tags":["Contacts"],"summary":"Update a contact","description":"Patch name, email, or metadata. Phone number is the identity column and cannot be changed via the API.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^ctc_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":200},"email":{"anyOf":[{"type":"string","maxLength":255,"format":"email"},{"type":"string","enum":[""]},{"type":"null"}]},"metadata":{"type":["object","null"],"additionalProperties":{}}}}}}},"responses":{"200":{"description":"Updated contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"delete":{"tags":["Contacts"],"summary":"Delete a contact","description":"Hard-deletes the contact and cascades to its conversations, messages, and label attachments. Irreversible.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^ctc_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteContactResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/messages/{id}/media":{"get":{"tags":["Messages"],"summary":"Redirect to the media asset for a message","description":"Returns a 302 redirect to the underlying CDN URL when the message has media (image, document, video, audio). Returns 404 if the message has no media or if media download is still in flight.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^msg_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"302":{"description":"Redirect to the media URL","headers":{"Location":{"description":"Public CDN URL for the asset","schema":{"type":"string"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/contacts/{id}/labels":{"post":{"tags":["Contacts"],"summary":"Attach a label to a contact","description":"Idempotent — attaching the same label twice is a no-op. The label and the contact must belong to the same team.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^ctc_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label_id":{"type":"string","pattern":"^lbl_[0-9A-HJKMNP-TV-Z]{26}$"}},"required":["label_id"]}}}},"responses":{"200":{"description":"Attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachContactLabelResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/contacts/{id}/labels/{label_id}":{"delete":{"tags":["Contacts"],"summary":"Detach a label from a contact","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^ctc_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^lbl_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"label_id","in":"path"}],"responses":{"200":{"description":"Detached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetachContactLabelResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/contacts/bulk_label":{"post":{"tags":["Contacts"],"summary":"Attach or detach a label across many contacts","description":"Apply or remove a label from up to 1000 contacts in a single transaction. Contacts not owned by the path-scoped account are silently skipped and counted under `skipped_cross_org`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"type":"array","items":{"type":"string","pattern":"^ctc_[0-9A-HJKMNP-TV-Z]{26}$"},"minItems":1,"maxItems":1000},"label_id":{"type":"string","pattern":"^lbl_[0-9A-HJKMNP-TV-Z]{26}$"},"operation":{"type":"string","enum":["attach","detach"]}},"required":["contact_ids","label_id","operation"]}}}},"responses":{"200":{"description":"Bulk operation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkLabelContactsResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/conversations/{id}/labels":{"post":{"tags":["Conversations"],"summary":"Attach a label to a conversation","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^cnv_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label_id":{"type":"string","pattern":"^lbl_[0-9A-HJKMNP-TV-Z]{26}$"}},"required":["label_id"]}}}},"responses":{"200":{"description":"Attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachConversationLabelResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/{phone_number_id}/conversations/{id}/labels/{label_id}":{"delete":{"tags":["Conversations"],"summary":"Detach a label from a conversation","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{6,20}$","example":"106540352242922","description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."},"required":true,"description":"Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).","name":"phone_number_id","in":"path"},{"schema":{"type":"string","pattern":"^cnv_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^lbl_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"label_id","in":"path"}],"responses":{"200":{"description":"Detached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetachConversationLabelResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Semantic failure (e.g. idempotency key reuse)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/labels":{"get":{"tags":["Labels"],"summary":"List labels","description":"List labels across every team in the organization.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Label list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLabelsResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"tags":["Labels"],"summary":"Create a label","description":"Create a label. Single-team orgs auto-resolve `team_id`; multi-team orgs MUST pass it. Names are unique per team — duplicates return `invalid_field_value`.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"team_id":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":50},"color":{"type":"string","enum":["gray","red","orange","amber","yellow","lime","green","emerald","teal","sky","blue","violet","pink"],"default":"gray"}},"required":["name"]}}}},"responses":{"200":{"description":"Label created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLabelResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/labels/{id}":{"get":{"tags":["Labels"],"summary":"Fetch a label by id","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^lbl_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Label resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetLabelResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"tags":["Labels"],"summary":"Update a label","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^lbl_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50},"color":{"type":"string","enum":["gray","red","orange","amber","yellow","lime","green","emerald","teal","sky","blue","violet","pink"]}}}}}},"responses":{"200":{"description":"Updated label","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLabelResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"delete":{"tags":["Labels"],"summary":"Delete a label","description":"Hard-deletes the label and cascades to every contact and conversation it was attached to (the row in the join table goes away, the parent resources stay).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^lbl_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteLabelResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/customers":{"get":{"tags":["Customers"],"summary":"List customers","description":"List end-customers (tenant-of-tenant) attached to the organization. Each customer can own one or more WhatsApp accounts via setup links. NOTE: a customer here is NOT a WhatsApp contact — see the `/{phone_number_id}/contacts` resource for those.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["pending","active","suspended","archived"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Customer list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListCustomersResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"tags":["Customers"],"summary":"Create a customer","description":"Create a new end-customer. Starts in `pending` status; transitions to `active` when the first WhatsApp account is connected via a setup link.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"team_id":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","maxLength":255,"format":"email"},"metadata":{"type":"object","additionalProperties":{}}},"required":["name"]}}}},"responses":{"200":{"description":"Customer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/customers/{id}":{"get":{"tags":["Customers"],"summary":"Fetch a customer by id","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^cus_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Customer resource (includes attached WhatsApp accounts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCustomerResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"tags":["Customers"],"summary":"Update a customer","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^cus_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":["string","null"],"maxLength":255,"format":"email"},"metadata":{"type":["object","null"],"additionalProperties":{}},"status":{"type":"string","enum":["pending","active","suspended"]}}}}}},"responses":{"200":{"description":"Updated customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"delete":{"tags":["Customers"],"summary":"Archive a customer","description":"Soft-archives the customer. WhatsApp accounts previously assigned remain in the database with `customer_id` unchanged — message history is never destroyed.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^cus_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveCustomerResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/customers/{id}/setup_links":{"get":{"tags":["Customers"],"summary":"List setup links for a customer","description":"Returns up to the 50 most-recent setup links — token plaintext is NEVER returned here (only at create time). Optional `status` query filters to `active` / `consumed` / `expired` / `revoked`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^cus_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["active","consumed","expired","revoked"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Setup link list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListCustomerSetupLinksResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"tags":["Customers"],"summary":"Generate a setup link","description":"Creates a one-time setup link the end-customer can use to complete Meta Embedded Signup. The plaintext token and full setup URL are returned EXACTLY ONCE — store them immediately.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^cus_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in_hours":{"type":"integer","minimum":1,"maximum":720},"success_redirect_url":{"type":"string","maxLength":2048,"format":"uri"},"failure_redirect_url":{"type":"string","maxLength":2048,"format":"uri"}}}}}},"responses":{"200":{"description":"Setup link created (token returned ONCE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerSetupLinkResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/customers/{id}/setup_links/{link_id}":{"patch":{"tags":["Customers"],"summary":"Update redirect URLs on an active setup link","description":"Recover from a typo in `success_redirect_url` / `failure_redirect_url` without revoking and regenerating the link. Only works while `status = active`; pass `null` to clear a redirect.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^cus_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^csl_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"link_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"success_redirect_url":{"anyOf":[{"type":"string","maxLength":2048,"format":"uri"},{"type":"null"}]},"failure_redirect_url":{"anyOf":[{"type":"string","maxLength":2048,"format":"uri"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Updated setup link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerSetupLinkResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Conflict (e.g. webhook subscription disabled, setup link inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"delete":{"tags":["Customers"],"summary":"Revoke a setup link","description":"Revoke a still-active link. Already-consumed or already-revoked links return `409`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^cus_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^csl_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true,"name":"link_id","in":"path"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeCustomerSetupLinkResponse"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"402":{"description":"Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Conflict (e.g. webhook subscription disabled, setup link inactive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}}},"webhooks":{}}