{"openapi":"3.0.3","info":{"title":"Pengo API","version":"1.0.0","description":"The Pengo REST API (v1). Authenticate with a workspace API key from Integrations → Developers → API keys:\n`Authorization: Bearer pgk_live_…`.\n\n**Scopes.** A key carries scopes; each operation lists the one it needs. `:write` includes `:read`.\nScopes: `conversations:read` (conversations, messages and tags), `conversations:write` (update conversations, send messages, add notes), `contacts:read` (contacts and visitors), `contacts:write` (create and update contacts), `team:read` (agents and their availability), `audit:read` (your workspace's audit log), `knowledge:read` (knowledge pushed through the api and its sources), `knowledge:write` (add, update and remove knowledge intelligence answers from), `webhooks:read` (webhook endpoints and recent events), `webhooks:write` (add, change and remove webhook endpoints (subscribe and unsubscribe)), `install:read` (websites, install code and whether the widget is live), `install:write` (add websites, allow domains and set the widget's look).\nKeys made before scopes existed have full access.\n\n**Websites.** A key reaches every website in its workspace. Pass `property_id` to pick one. It is required\nwhen the workspace has more than one website (a 400 says so); a workspace with one website may leave it out.\n\n**Pagination.** Lists return `pagination.next_cursor`; pass it back as `cursor` for the next page.\n\n**Idempotency.** POSTs that create something accept an `Idempotency-Key` header. A retry with the same\nkey and body within 24 hours returns the first response (`Idempotent-Replayed: true`).\n\n**Rate limits.** Per key, per minute, by plan; every response carries `X-RateLimit-*` headers and a 429\ncarries `Retry-After`.\n\n**Errors** always look like `{ \"error\": { \"code\", \"message\", \"details\"? }, \"request_id\" }`.\n\n**Webhooks.** Add endpoints in Settings → Webhooks or with `POST /api/v1/webhooks` (REST hooks: subscribe with a\nPOST, unsubscribe with a DELETE). Each delivery is a JSON POST of\n`{ \"id\", \"api_version\", \"event\", \"created_at\", \"timestamp\", \"property_id\", \"data\" }` (the `WebhookEvent.*` schemas).\n- `id` (`evt_…`, also in the `X-Pengo-Event-Id` header) is the same on every retry and redelivery: dedupe on it.\n- `api_version` is the shape of `data` (`2026-11-01`). Fields are only ever added. Deprecated aliases stay:\n  `timestamp` (= `created_at`), `previous_status` (= `from_status`) and, on bulk `chat.assigned`, `action`, `value`, `assigned_to`, `updated_at`.\n  `chat_id` and `conversation_id` are the same id on every conversation event.\n- Signed with the endpoint's secret: `X-Pengo-Signature-V2: t=<unix>,v1=<hex hmac_sha256(secret, \"<t>.<body>\")>`. For 24 hours\n  after a rotation the header carries a second `v1=` made with the previous secret; accept the request when any `v1` matches.\n  Reject timestamps more than 5 minutes old. The older `X-Pengo-Signature: sha256=<hex hmac(secret, body)>` is still sent,\n  signed with the current secret only.\n- Any 2xx answer within 6 seconds counts as delivered. Anything else is retried for about 3 days (1 min, 5 min, 30 min,\n  1 h, 2 h, 4 h, 8 h, then every 12 h). An endpoint that fails for 5 days straight is paused and its owner emailed.\n- Settings → Webhooks shows every attempt, and can resend one event or replay everything since a time (30 days back).\n  `GET /api/v1/events` lists recent events (a REST hook's sample data).\n\nEvents:\n- `chat.created`: A conversation started: in the widget, on a channel (email, WhatsApp, SMS, Messenger, Instagram) or by a teammate.\n- `message.sent`: Any message in a conversation, from any channel: the visitor's, a teammate's or Intelligence's.\n- `chat.assigned`: A conversation was assigned or transferred to a teammate.\n- `chat.status_changed`: A conversation's status changed.\n- `chat.resolved`: A teammate resolved a conversation.\n- `chat.ai_resolved`: Pengo Intelligence resolved a conversation on its own.\n- `chat.closed`: A conversation was closed.\n- `chat.rated`: A visitor rated a conversation.\n- `chat.needs_person`: A visitor is waiting and a person must answer: Intelligence is off, handed off, stalled or asked the team. Once per wait.\n- `lead.created`: A new lead was captured: in chat, by the in-chat email ask, by Pengo Intelligence or by a booking.\n- `lead.qualified`: A lead answered enough of your qualifying questions to count as qualified.\n- `lead.hot`: A lead's score crossed your hot threshold, or a teammate marked it hot.\n- `lead.booked`: A lead booked a meeting (the booking rides along).\n- `lead.won`: A teammate marked a lead as won.\n- `lead.lost`: A teammate marked a lead as lost.\n- `booking.created`: A visitor booked a meeting from the chat.\n- `contact.created`: A contact was added by a teammate or through the API.\n- `contact.updated`: A teammate or the API changed a contact's details or attributes.\n- `action.requested`: Pengo or a teammate asked for a Pengo Action (it may wait for approval).\n- `action.approved`: A teammate approved a Pengo Action, or ran one Pengo got ready for them.\n- `action.completed`: A Pengo Action ran: it went through, failed, or the other system didn't answer.\n- `order.updated`: An order in your connected store was confirmed, shipped, delivered, delayed, cancelled or refunded. Once per change; no customer details.\n- `checkout.abandoned`: A Shopify shopper left a checkout and its first reminder came due (abandoned checkout reminders on). Once per checkout; no customer details.\n- `checkout.recovered`: A shopper placed an order through a checkout within 7 days of Pengo's reminder. Once per checkout.","contact":{"name":"Pengo Support","email":"support@pengo.chat"}},"servers":[{"url":"https://app.pengo.chat","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Conversations","description":"Conversations, their messages and internal notes"},{"name":"Contacts","description":"People who chatted or were added through the API"},{"name":"Visitors","description":"Website visitors (contacts include them)"},{"name":"Team","description":"Agents in the workspace"},{"name":"Tags","description":"Conversation tags"},{"name":"Audit log","description":"Who did what in the workspace"},{"name":"Knowledge","description":"Push documents from your own systems for Pengo Intelligence to answer from"},{"name":"Webhooks","description":"Webhook endpoints (REST hook subscriptions) and the events Pengo sends them"},{"name":"Meta","description":"This specification"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"Workspace API key (Integrations → Developers → API keys), sent as `Authorization: Bearer <key>`"}},"parameters":{"PropertyId":{"in":"query","name":"property_id","schema":{"type":"string","format":"uuid"},"description":"Website to act on. Required when the workspace has more than one website."},"Limit":{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size"},"Cursor":{"in":"query","name":"cursor","schema":{"type":"string"},"description":"`pagination.next_cursor` from the previous page"},"IdempotencyKey":{"in":"header","name":"Idempotency-Key","schema":{"type":"string","maxLength":255},"description":"Makes a retried create safe: the same key and body within 24 hours return the first response."}},"schemas":{"Error":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","insufficient_scope","plan_required","forbidden","not_found","conflict","idempotency_key_reused","unprocessable","rate_limited","unavailable","internal_error"]},"message":{"type":"string"},"details":{"description":"Per-field problems for invalid_request","nullable":true}}},"request_id":{"type":"string"}}},"Pagination":{"type":"object","required":["limit","has_more","next_cursor"],"properties":{"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}},"Conversation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"property_id":{"type":"string","format":"uuid"},"visitor_id":{"type":"string","format":"uuid","nullable":true},"visitor_name":{"type":"string","nullable":true},"visitor_email":{"type":"string","nullable":true},"status":{"type":"string","example":"open"},"priority":{"type":"string","nullable":true,"enum":["urgent","high","normal","low",null]},"assigned_to":{"type":"string","format":"uuid","nullable":true},"team_id":{"type":"string","format":"uuid","nullable":true,"description":"The team the conversation is routed to"},"channel":{"type":"string","example":"web"},"tags":{"type":"array","items":{"type":"string"}},"last_message":{"type":"string","nullable":true},"last_message_at":{"type":"string","format":"date-time","nullable":true},"first_response_at":{"type":"string","format":"date-time","nullable":true},"resolved_at":{"type":"string","format":"date-time","nullable":true},"rating":{"type":"integer","nullable":true},"custom_fields":{"type":"object","description":"Conversation field values by key: text, number, yes/no or a date (YYYY-MM-DD or ISO), as defined in Settings → Contact data → Conversations","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"example":{"order_id":"A-1042","refund_amount":49.5,"reason":"Damaged"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Message":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"chat_id":{"type":"string","format":"uuid"},"content":{"type":"string"},"sender_id":{"type":"string","format":"uuid","nullable":true},"sender_type":{"type":"string","enum":["visitor","agent","bot","system"]},"client_message_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","format":"uuid"},"content":{"type":"string"},"is_pinned":{"type":"boolean"},"author_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"property_id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true,"description":"Your user id, set by a verified identify"},"attributes":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"tags":{"type":"array","items":{"type":"string"}},"country_code":{"type":"string","nullable":true},"is_online":{"type":"boolean"},"first_seen_at":{"type":"string","format":"date-time","nullable":true},"last_seen_at":{"type":"string","format":"date-time","nullable":true},"last_chat_at":{"type":"string","format":"date-time","nullable":true},"total_chats":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Visitor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"is_online":{"type":"boolean"},"has_active_chat":{"type":"boolean"},"last_seen_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"country_code":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"company":{"type":"string","nullable":true},"company_id":{"type":"string","format":"uuid","nullable":true},"custom_attributes":{"type":"object","additionalProperties":true}}},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"role":{"type":"string","enum":["owner","manager","agent","viewer"]},"website_scope":{"type":"string","enum":["all","selected"]},"availability_status":{"type":"string","example":"online"},"joined_at":{"type":"string","format":"date-time","nullable":true}}},"Tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"property_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"usage_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time","nullable":true}}},"AuditLogEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"property_id":{"type":"string","format":"uuid"},"actor_id":{"type":"string","format":"uuid","nullable":true},"actor_email":{"type":"string","nullable":true},"action":{"type":"string","example":"settings.updated"},"target_type":{"type":"string","nullable":true},"target_id":{"type":"string","format":"uuid","nullable":true},"metadata":{"type":"object","additionalProperties":true},"ip_address":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"KnowledgeSource":{"type":"object","description":"A named group of documents pushed through the API. Pengo never syncs it: your system pushes changes and deletions.","properties":{"id":{"type":"string","format":"uuid"},"property_id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"API"},"enabled":{"type":"boolean","description":"Off when turned off in Intelligence → Knowledge: its documents aren't used in answers"},"document_count":{"type":"integer"},"chunk_count":{"type":"integer","description":"Searchable passages"},"char_count":{"type":"integer","description":"Characters of text, counted against the website's training content"},"last_pushed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"KnowledgeDocument":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"property_id":{"type":"string","format":"uuid"},"source_id":{"type":"string","format":"uuid"},"external_id":{"type":"string","description":"Your id for the document, unique within its source"},"title":{"type":"string"},"url":{"type":"string","nullable":true,"description":"Where the document lives"},"is_public":{"type":"boolean","description":"Whether answers may link to `url` (public audience only)"},"audience":{"type":"string","enum":["public","verified","internal"],"description":"public: anyone; verified: customers whose identity is verified; internal: your team only (agent assist), never customers"},"channels":{"type":"array","nullable":true,"items":{"type":"string","enum":["chat","email","whatsapp","sms","messenger","instagram"]},"description":"Channels whose answers may use it; null = all"},"enabled":{"type":"boolean"},"status":{"type":"string","enum":["pending","indexing","active","error"],"description":"`active` once it answers questions"},"error":{"type":"string","nullable":true},"char_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"indexed_at":{"type":"string","format":"date-time","nullable":true}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","description":"The endpoint's id (to update it or unsubscribe)"},"url":{"type":"string","example":"https://hooks.example.com/pengo"},"events":{"type":"array","items":{"type":"string","enum":["chat.created","message.sent","chat.assigned","chat.status_changed","chat.resolved","chat.ai_resolved","chat.closed","chat.rated","chat.needs_person","lead.created","lead.qualified","lead.hot","lead.booked","lead.won","lead.lost","booking.created","contact.created","contact.updated","action.requested","action.approved","action.completed","order.updated","checkout.abandoned","checkout.recovered"]}},"active":{"type":"boolean","description":"Off when paused, by a teammate or by Pengo after 5 days of failures"},"disabled_reason":{"type":"string","nullable":true,"enum":["failing",null],"description":"`failing`: Pengo paused it after 5 days without a successful delivery"},"disabled_at":{"type":"string","format":"date-time","nullable":true},"secret_hint":{"type":"string","nullable":true,"description":"The signing secret's last four characters"},"secret_rotated_at":{"type":"string","format":"date-time","nullable":true},"previous_secret_expires_at":{"type":"string","format":"date-time","nullable":true,"description":"After a rotation: when the previous secret stops signing deliveries"},"created_at":{"type":"string","format":"date-time","nullable":true}}},"Event":{"type":"object","description":"A stored webhook event: exactly the body Pengo sent (kept 30 days)","properties":{"id":{"type":"string","example":"evt_3f9a1c2b7d4e5f60718293a4"},"type":{"type":"string","enum":["chat.created","message.sent","chat.assigned","chat.status_changed","chat.resolved","chat.ai_resolved","chat.closed","chat.rated","chat.needs_person","lead.created","lead.qualified","lead.hot","lead.booked","lead.won","lead.lost","booking.created","contact.created","contact.updated","action.requested","action.approved","action.completed","order.updated","checkout.abandoned","checkout.recovered"]},"api_version":{"type":"string","example":"2026-11-01"},"created_at":{"type":"string","format":"date-time"},"payload":{"type":"object","description":"The delivered body (one of the WebhookEvent.* schemas)"}}},"WebhookEvent.chat.created":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["chat.created"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"visitor_id":{"nullable":true,"type":"string","format":"uuid"},"visitor_email":{"nullable":true,"type":"string"},"visitor_name":{"nullable":true,"type":"string"},"assigned_agent_id":{"nullable":true,"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}},"required":["chat_id","conversation_id","team_id","visitor_id","visitor_email","visitor_name","assigned_agent_id","created_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.message.sent":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["message.sent"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"sender_id":{"nullable":true,"description":"The visitor, teammate or API caller who sent it (null for Intelligence and system messages).","type":"string"},"sender_type":{"type":"string","description":"visitor, agent, bot or system."},"content":{"type":"string"},"has_attachment":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"scheduled":{"description":"True for a reply a teammate scheduled with Send later.","type":"boolean"},"rich_response":{"description":"For a visitor's answer to a button, form or card: what they chose or entered."}},"required":["chat_id","conversation_id","team_id","message_id","sender_id","sender_type","content","has_attachment","created_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.chat.assigned":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["chat.assigned"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"from_agent_id":{"nullable":true,"type":"string","format":"uuid"},"to_agent_id":{"nullable":true,"type":"string","format":"uuid"},"source":{"nullable":true,"description":"How it was assigned: manual, transfer, routing, agent_reply, agent_accept, bulk…","type":"string"},"assigned_at":{"type":"string","format":"date-time"},"department":{"nullable":true,"type":"string"},"notes":{"description":"A transfer's handover note.","nullable":true,"type":"string"},"transfer_history":{"type":"array","items":{}},"transferred_at":{"type":"string","format":"date-time"},"action":{"description":"Deprecated: bulk assignments only; use source.","type":"string"},"value":{"description":"Deprecated: bulk assignments only; use to_agent_id.","nullable":true,"type":"string"},"status":{"type":"string"},"assigned_to":{"description":"Deprecated: bulk assignments only; use to_agent_id.","nullable":true,"type":"string","format":"uuid"},"updated_at":{"description":"Deprecated: bulk assignments only; use assigned_at.","type":"string","format":"date-time"}},"required":["chat_id","conversation_id","team_id","from_agent_id","to_agent_id","source","assigned_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.chat.status_changed":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["chat.status_changed"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"status":{"type":"string"},"from_status":{"nullable":true,"type":"string"},"previous_status":{"nullable":true,"description":"Deprecated: same as from_status.","type":"string"},"action":{"type":"string"},"value":{"nullable":true,"type":"string"},"reason":{"nullable":true,"type":"string"},"assigned_to":{"nullable":true,"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"},"reopened_at":{"type":"string","format":"date-time"}},"required":["chat_id","conversation_id","team_id","status","from_status","previous_status","action","value","assigned_to","updated_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.chat.resolved":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["chat.resolved"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"resolved_at":{"type":"string","format":"date-time"},"ended_reason":{"nullable":true,"type":"string"}},"required":["chat_id","conversation_id","team_id","resolved_at","ended_reason"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.chat.ai_resolved":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["chat.ai_resolved"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"confirmed_at":{"type":"string","format":"date-time"}},"required":["chat_id","conversation_id","team_id","confirmed_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.chat.closed":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["chat.closed"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"resolved_at":{"type":"string","format":"date-time"},"ended_reason":{"nullable":true,"type":"string"}},"required":["chat_id","conversation_id","team_id","resolved_at","ended_reason"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.chat.rated":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["chat.rated"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"rating_id":{"nullable":true,"type":"string","format":"uuid"},"rating":{"type":"number"},"rating_type":{"type":"string","description":"stars, thumbs, emoji or email."},"feedback":{"nullable":true,"type":"string"},"sentiment":{"nullable":true,"type":"string"},"sentiment_score":{"nullable":true,"type":"number"},"visitor_id":{"nullable":true,"type":"string","format":"uuid"},"assigned_to":{"nullable":true,"type":"string","format":"uuid"},"rated_at":{"type":"string","format":"date-time"}},"required":["chat_id","conversation_id","team_id","rating_id","rating","rating_type","feedback","sentiment","visitor_id","assigned_to","rated_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.lead.created":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["lead.created"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"status":{"nullable":true,"type":"string"},"score":{"nullable":true,"type":"number"},"qualification":{},"chat_id":{"nullable":true,"type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"type":"string","format":"uuid"},"booking":{"description":"booking.created and lead.booked: the meeting.","type":"object","properties":{},"additionalProperties":{}},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as the envelope's created_at."}},"required":["lead_id","email","name","phone","status","score","chat_id","conversation_id","timestamp"],"additionalProperties":{}}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.lead.qualified":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["lead.qualified"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"status":{"nullable":true,"type":"string"},"score":{"nullable":true,"type":"number"},"qualification":{},"chat_id":{"nullable":true,"type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"type":"string","format":"uuid"},"booking":{"description":"booking.created and lead.booked: the meeting.","type":"object","properties":{},"additionalProperties":{}},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as the envelope's created_at."}},"required":["lead_id","email","name","phone","status","score","chat_id","conversation_id","timestamp"],"additionalProperties":{}}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.lead.hot":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["lead.hot"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"status":{"nullable":true,"type":"string"},"score":{"nullable":true,"type":"number"},"qualification":{},"chat_id":{"nullable":true,"type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"type":"string","format":"uuid"},"booking":{"description":"booking.created and lead.booked: the meeting.","type":"object","properties":{},"additionalProperties":{}},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as the envelope's created_at."}},"required":["lead_id","email","name","phone","status","score","chat_id","conversation_id","timestamp"],"additionalProperties":{}}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.lead.booked":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["lead.booked"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"status":{"nullable":true,"type":"string"},"score":{"nullable":true,"type":"number"},"qualification":{},"chat_id":{"nullable":true,"type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"type":"string","format":"uuid"},"booking":{"description":"booking.created and lead.booked: the meeting.","type":"object","properties":{},"additionalProperties":{}},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as the envelope's created_at."}},"required":["lead_id","email","name","phone","status","score","chat_id","conversation_id","timestamp"],"additionalProperties":{}}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.lead.won":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["lead.won"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"status":{"nullable":true,"type":"string"},"score":{"nullable":true,"type":"number"},"qualification":{},"chat_id":{"nullable":true,"type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"type":"string","format":"uuid"},"booking":{"description":"booking.created and lead.booked: the meeting.","type":"object","properties":{},"additionalProperties":{}},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as the envelope's created_at."}},"required":["lead_id","email","name","phone","status","score","chat_id","conversation_id","timestamp"],"additionalProperties":{}}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.lead.lost":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["lead.lost"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"status":{"nullable":true,"type":"string"},"score":{"nullable":true,"type":"number"},"qualification":{},"chat_id":{"nullable":true,"type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"type":"string","format":"uuid"},"booking":{"description":"booking.created and lead.booked: the meeting.","type":"object","properties":{},"additionalProperties":{}},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as the envelope's created_at."}},"required":["lead_id","email","name","phone","status","score","chat_id","conversation_id","timestamp"],"additionalProperties":{}}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.booking.created":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["booking.created"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"status":{"nullable":true,"type":"string"},"score":{"nullable":true,"type":"number"},"qualification":{},"chat_id":{"nullable":true,"type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"type":"string","format":"uuid"},"booking":{"description":"booking.created and lead.booked: the meeting.","type":"object","properties":{},"additionalProperties":{}},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as the envelope's created_at."}},"required":["lead_id","email","name","phone","status","score","chat_id","conversation_id","timestamp"],"additionalProperties":{}}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.contact.created":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["contact.created"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid","description":"Same as id."},"property_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"external_id":{"nullable":true,"type":"string"},"attributes":{"type":"object","additionalProperties":{}},"tags":{"type":"array","items":{"type":"string"}},"country_code":{"nullable":true,"type":"string"},"is_online":{"type":"boolean"},"first_seen_at":{"nullable":true,"type":"string","format":"date-time"},"last_seen_at":{"nullable":true,"type":"string","format":"date-time"},"last_chat_at":{"nullable":true,"type":"string","format":"date-time"},"total_chats":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"nullable":true,"type":"string","format":"date-time"},"changed":{"description":"contact.updated: the fields this change set.","type":"array","items":{"type":"string"}}},"required":["id","contact_id","property_id","email","name","phone","company","external_id","attributes","tags","country_code","is_online","first_seen_at","last_seen_at","last_chat_at","total_chats","created_at","updated_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.contact.updated":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["contact.updated"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid","description":"Same as id."},"property_id":{"type":"string","format":"uuid"},"email":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"external_id":{"nullable":true,"type":"string"},"attributes":{"type":"object","additionalProperties":{}},"tags":{"type":"array","items":{"type":"string"}},"country_code":{"nullable":true,"type":"string"},"is_online":{"type":"boolean"},"first_seen_at":{"nullable":true,"type":"string","format":"date-time"},"last_seen_at":{"nullable":true,"type":"string","format":"date-time"},"last_chat_at":{"nullable":true,"type":"string","format":"date-time"},"total_chats":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"nullable":true,"type":"string","format":"date-time"},"changed":{"description":"contact.updated: the fields this change set.","type":"array","items":{"type":"string"}}},"required":["id","contact_id","property_id","email","name","phone","company","external_id","attributes","tags","country_code","is_online","first_seen_at","last_seen_at","last_chat_at","total_chats","created_at","updated_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.chat.needs_person":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["chat.needs_person"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"chat_id":{"type":"string","format":"uuid","description":"The conversation (the API calls it a conversation: same id)."},"conversation_id":{"type":"string","format":"uuid","description":"Same as chat_id, under the public API's name."},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"waiting_since":{"nullable":true,"description":"Since when the visitor has waited on a reply.","type":"string","format":"date-time"},"reason":{"type":"string","description":"Why a person must answer: off (Intelligence isn't answering), handed_off (it handed the chat to the team), stalled (it hasn't replied in time) or question_for_team (it passed a question to the team)."},"status":{"nullable":true,"type":"string"},"assigned_to":{"nullable":true,"type":"string","format":"uuid"},"visitor_id":{"nullable":true,"type":"string","format":"uuid"}},"required":["chat_id","conversation_id","team_id","waiting_since","reason","status","assigned_to","visitor_id"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.action.requested":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["action.requested"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"execution_id":{"type":"string","format":"uuid","description":"The run of the Action (the same id on its requested, approved and completed events)."},"action_key":{"type":"string","description":"Which Pengo Action, e.g. shopify_refund_order."},"chat_id":{"nullable":true,"description":"The conversation it was asked for in, if any.","type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"title":{"nullable":true,"description":"What it does, as approvers see it.","type":"string"},"status":{"type":"string","description":"pending_approval, staged, running, approved, executed or failed."},"requested_by":{"type":"string","description":"Who asked: ai, agent, workflow or system."},"requested_at":{"type":"string","format":"date-time"},"needs_approval":{"type":"boolean","description":"True when it waits for a teammate (approval, or got ready for one to run)."}},"required":["execution_id","action_key","chat_id","conversation_id","team_id","title","status","requested_by","requested_at","needs_approval"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.action.approved":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["action.approved"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"execution_id":{"type":"string","format":"uuid","description":"The run of the Action (the same id on its requested, approved and completed events)."},"action_key":{"type":"string","description":"Which Pengo Action, e.g. shopify_refund_order."},"chat_id":{"nullable":true,"description":"The conversation it was asked for in, if any.","type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"title":{"nullable":true,"description":"What it does, as approvers see it.","type":"string"},"status":{"type":"string","description":"pending_approval, staged, running, approved, executed or failed."},"requested_by":{"type":"string","description":"Who asked: ai, agent, workflow or system."},"requested_at":{"type":"string","format":"date-time"},"decided_by":{"nullable":true,"type":"string","format":"uuid"},"decided_via":{"nullable":true,"description":"Where it was approved: inbox, ios, android, web_push, email, slack, api or system.","type":"string"},"decided_at":{"nullable":true,"type":"string","format":"date-time"}},"required":["execution_id","action_key","chat_id","conversation_id","team_id","title","status","requested_by","requested_at","decided_by","decided_via","decided_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.action.completed":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["action.completed"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"execution_id":{"type":"string","format":"uuid","description":"The run of the Action (the same id on its requested, approved and completed events)."},"action_key":{"type":"string","description":"Which Pengo Action, e.g. shopify_refund_order."},"chat_id":{"nullable":true,"description":"The conversation it was asked for in, if any.","type":"string","format":"uuid"},"conversation_id":{"nullable":true,"description":"Same as chat_id.","type":"string","format":"uuid"},"team_id":{"nullable":true,"description":"The team the conversation is routed to, if any.","type":"string","format":"uuid"},"title":{"nullable":true,"description":"What it does, as approvers see it.","type":"string"},"status":{"type":"string","description":"pending_approval, staged, running, approved, executed or failed."},"requested_by":{"type":"string","description":"Who asked: ai, agent, workflow or system."},"requested_at":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["executed","failed","unconfirmed"],"description":"unconfirmed: the other system didn't answer, so whether it happened is being checked."},"error":{"nullable":true,"type":"string"},"decided_by":{"nullable":true,"type":"string","format":"uuid"},"executed_at":{"nullable":true,"type":"string","format":"date-time"}},"required":["execution_id","action_key","chat_id","conversation_id","team_id","title","status","requested_by","requested_at","outcome","error","decided_by","executed_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.order.updated":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["order.updated"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"order_event_id":{"type":"string","format":"uuid","description":"Pengo's id for this change of the order: one event each, the same on every retry."},"provider":{"type":"string","enum":["shopify","woocommerce","bigcommerce"],"description":"The store the order or checkout is in."},"order_id":{"type":"string","description":"The order's id in the store."},"order_name":{"nullable":true,"description":"The order's name as the customer sees it, e.g. #1042.","type":"string"},"kind":{"type":"string","enum":["confirmed","shipped","out_for_delivery","delivered","delivery_problem","delayed","cancelled","refunded"],"description":"What changed. Only the newest change of a shipment or order is sent: one the store reported out of order is not."},"occurred_at":{"type":"string","format":"date-time","description":"When the store says it happened."},"tracking":{"nullable":true,"description":"The shipment's tracking, when the store gave it.","type":"object","properties":{"carrier":{"nullable":true,"type":"string"},"number":{"nullable":true,"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["carrier","number","url"],"additionalProperties":false},"estimated_delivery":{"nullable":true,"description":"The carrier's delivery estimate, when there is one.","type":"string","format":"date-time"}},"required":["order_event_id","provider","order_id","order_name","kind","occurred_at","tracking","estimated_delivery"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.checkout.abandoned":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["checkout.abandoned"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"checkout_id":{"type":"string","description":"The checkout's id in the store."},"provider":{"type":"string","enum":["shopify","woocommerce","bigcommerce"],"description":"The store the order or checkout is in."},"item_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many items are in the cart."},"total":{"nullable":true,"description":"The cart's total as a decimal string, in currency.","type":"string"},"currency":{"nullable":true,"description":"ISO 4217, e.g. USD.","type":"string"},"abandoned_at":{"type":"string","format":"date-time","description":"The cart's last change: the shopper hasn't come back to it since."}},"required":["checkout_id","provider","item_count","total","currency","abandoned_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.checkout.recovered":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["checkout.recovered"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"checkout_id":{"type":"string","description":"The checkout's id in the store."},"provider":{"type":"string","enum":["shopify","woocommerce","bigcommerce"],"description":"The store the order or checkout is in."},"item_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many items are in the cart."},"total":{"nullable":true,"description":"The cart's total as a decimal string, in currency.","type":"string"},"currency":{"nullable":true,"description":"ISO 4217, e.g. USD.","type":"string"},"order_id":{"type":"string","description":"The order the shopper placed through the checkout."},"recovered_at":{"type":"string","format":"date-time","description":"When the order was placed."},"reminded_at":{"nullable":true,"description":"When Pengo's last reminder went before the order (within 7 days: that's what counts as recovered).","type":"string","format":"date-time"}},"required":["checkout_id","provider","item_count","total","currency","order_id","recovered_at","reminded_at"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false},"WebhookEvent.ping":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9]+$","description":"Unique per event and the same on every retry and redelivery: dedupe on it."},"api_version":{"type":"string","description":"The shape of data. This build sends 2026-11-01."},"event":{"type":"string","enum":["ping"]},"created_at":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time","description":"Deprecated: same as created_at."},"property_id":{"type":"string","format":"uuid","description":"The website the event happened on."},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["id","api_version","event","created_at","timestamp","property_id","data"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Request is not valid"},"request_id":"lz3k9a-4f8e2c1d"}}}},"Unauthorized":{"description":"Missing, invalid, revoked or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"This API key has expired"},"request_id":"lz3k9a-4f8e2c1d"}}}},"PaymentRequired":{"description":"The workspace's plan doesn't include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"API access is available on Growth and above."},"request_id":"lz3k9a-4f8e2c1d"}}}},"Forbidden":{"description":"The key lacks the scope this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key is missing the contacts:write scope"},"request_id":"lz3k9a-4f8e2c1d"}}}},"NotFound":{"description":"Not found in this key's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Conversation not found"},"request_id":"lz3k9a-4f8e2c1d"}}}},"Conflict":{"description":"A request with this Idempotency-Key is still running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"A request with this Idempotency-Key is still in progress"},"request_id":"lz3k9a-4f8e2c1d"}}}},"Unprocessable":{"description":"Valid JSON that can't be applied (or an Idempotency-Key reused with a different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unprocessable","message":"attributes.plan is not one of the options"},"request_id":"lz3k9a-4f8e2c1d"}}}},"KnowledgeLimit":{"description":"The document would take the website past its plan's training content (`details.reason` is `kb_training`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"This would take the website past its plan's training content. Remove some knowledge or upgrade.","details":{"reason":"kb_training"}},"request_id":"lz3k9a-4f8e2c1d"}}}},"Unavailable":{"description":"Saved but not indexed yet; retry the same request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The document was saved but couldn't be indexed. Retry the same request."},"request_id":"lz3k9a-4f8e2c1d"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}},"RateLimited":{"description":"Rate limit exceeded for this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 300 requests per minute exceeded for this key"},"request_id":"lz3k9a-4f8e2c1d"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests per minute for this key"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in this window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time (seconds) the window resets"}}}}},"paths":{"/api/v1/agents":{"get":{"tags":["Team"],"summary":"List agents","description":"Everyone active in the key's workspace, owner included. With `property_id`, only the people who can be assigned that website's conversations (no viewers). Scope `team:read`.","parameters":[{"in":"query","name":"property_id","schema":{"type":"string","format":"uuid"},"description":"Only agents of this website"}],"responses":{"200":{"description":"The workspace's agents, by name","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/audit-logs":{"get":{"tags":["Audit log"],"summary":"List audit log entries","description":"Newest first, across every website in the key's workspace (or one, with `property_id`). Scope `audit:read`.","parameters":[{"in":"query","name":"property_id","schema":{"type":"string","format":"uuid"},"description":"Only this website's entries"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"in":"query","name":"action","schema":{"type":"string"},"description":"Only this action, e.g. `settings.updated`"},{"in":"query","name":"actor_id","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"until","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A page of audit log entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLogEntry"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","description":"Newest first. By default only contacts with an email; `include_anonymous=true` adds every visitor. Scope `contacts:read`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"in":"query","name":"email","schema":{"type":"string","format":"email"},"description":"Only the contact(s) with this email (case-insensitive)"},{"in":"query","name":"include_anonymous","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"A page of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Contacts"],"summary":"Create or update a contact by email","description":"Upsert keyed on email: updates the website's contact with this email (200, `created: false`) or creates one (201, `created: true`). Attributes merge into the existing ones; null removes one. Attributes defined in Settings → Contact data are checked against their type (number, yes/no, date YYYY-MM-DD, list option) and stored typed; a value that doesn't fit is a 422 naming the key. Other keys store as text. Scope `contacts:write`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"attributes":{"type":"object","additionalProperties":{"nullable":true,"oneOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}}}}}}},"responses":{"200":{"description":"Existing contact updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"},"created":{"type":"boolean"}}}}}},"201":{"description":"Contact created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"},"created":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Get a contact","description":"Scope `contacts:read`.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/PropertyId"}],"responses":{"200":{"description":"The contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Contacts"],"summary":"Update a contact","description":"Change name, email, phone, company or attributes. Attributes merge into the existing ones; null removes one. Attributes defined in Settings → Contact data are checked against their type and stored typed; a value that doesn't fit is a 422 naming the key. Other keys store as text. An email another contact of this website already has is a 409. Scope `contacts:write`.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/PropertyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","nullable":true},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"attributes":{"type":"object","additionalProperties":{"nullable":true,"oneOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}}}}}}},"responses":{"200":{"description":"The updated contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Contacts"],"summary":"Delete a contact (GDPR erasure)","description":"Erases the person, as Settings → Privacy & data does for a data request: their messages, files, leads, bookings, ratings, browsing history and the webhook events about them are deleted, and what must stay for reports (the conversation rows, the contact row) is anonymized. It can't be undone. A 500 means some of it didn't finish: send the same request again. Scope `contacts:write`.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/PropertyId"}],"responses":{"200":{"description":"Erased","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"messages_deleted":{"type":"integer"},"chats_anonymized":{"type":"integer"},"leads_deleted":{"type":"integer"},"files_deleted":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","description":"Newest first. Scope `conversations:read`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"in":"query","name":"status","schema":{"type":"string","enum":["open","pending","snoozed","resolved"]}},{"in":"query","name":"assigned_to","schema":{"type":"string","format":"uuid"},"description":"Only conversations assigned to this agent"},{"in":"query","name":"team_id","schema":{"type":"string","format":"uuid"},"description":"Only conversations routed to this team"},{"in":"query","name":"offset","deprecated":true,"schema":{"type":"integer","minimum":0},"description":"Use `cursor` instead. Ignored when `cursor` is set."}],"responses":{"200":{"description":"A page of conversations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/conversations/{id}":{"get":{"tags":["Conversations"],"summary":"Get a conversation","description":"Scope `conversations:read`.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/PropertyId"}],"responses":{"200":{"description":"The conversation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Conversations"],"summary":"Update a conversation","description":"Change status, assignee, priority, tags or conversation fields. Scope `conversations:write`. `assigned_to` must be an agent of the conversation's website (or null to unassign). `tags` replaces the list. `custom_fields` sets the fields it names (null clears one) and leaves the rest; each value must fit its field's type (422 otherwise). Resolving is refused (409 `conflict`) while a field that's required to resolve is empty; set it in the same request.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/PropertyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","pending","snoozed","resolved"]},"assigned_to":{"type":"string","format":"uuid","nullable":true},"priority":{"type":"string","enum":["urgent","high","normal","low"]},"tags":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":64}},"custom_fields":{"type":"object","additionalProperties":true,"example":{"order_id":"A-1042","reason":"Damaged"}}}}}}},"responses":{"200":{"description":"The updated conversation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/conversations/{id}/messages":{"post":{"tags":["Conversations"],"summary":"Send a message","description":"Send a message in a conversation as an agent or bot. Scope `conversations:write`. An agent message needs a `sender_id`, an agent of the conversation's website; a bot message may leave it out. Retry safely with an `Idempotency-Key` header or a `client_message_id` (unique per conversation; a retry returns the stored message with `deduplicated: true`).","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":10000},"sender_id":{"type":"string","format":"uuid","description":"The sending agent's id. Required when sender_type is agent; optional for a bot."},"sender_type":{"type":"string","enum":["agent","bot"],"default":"agent"},"client_message_id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9._:-]{1,64}$"}}}}}},"responses":{"200":{"description":"Replay of an already-stored client_message_id (`deduplicated: true`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"},"deduplicated":{"type":"boolean"}}}}}},"201":{"description":"Message sent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"tags":["Conversations"],"summary":"List messages","description":"Oldest first. Scope `conversations:read`.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"in":"query","name":"offset","deprecated":true,"schema":{"type":"integer","minimum":0},"description":"Use `cursor` instead. Ignored when `cursor` is set."}],"responses":{"200":{"description":"A page of messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/conversations/{id}/notes":{"post":{"tags":["Conversations"],"summary":"Add an internal note","description":"A note only agents see. Scope `conversations:write`. `author_id` must be an agent of the conversation's website; without it the note is by the key's creator (while they still work this website) or else the workspace owner.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":10000},"author_id":{"type":"string","format":"uuid"},"is_pinned":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Note added","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/events":{"get":{"tags":["Webhooks"],"summary":"List recent events","description":"The webhook events Pengo stored for this website, newest first: exactly the bodies it sent, kept 30 days. Only events at least one endpoint subscribed to are stored. Useful as a REST hook's sample data (pass `type` and a small `limit`) and to catch up after an outage. Scope `webhooks:read`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"in":"query","name":"type","schema":{"type":"string"},"description":"Only this event type, e.g. `message.sent`"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"The events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/knowledge/documents":{"get":{"tags":["Knowledge"],"summary":"List knowledge documents pushed through the API","description":"Newest first. Only documents in API sources; pages, files and connected apps aren't listed here. Scope `knowledge:read`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"in":"query","name":"source","schema":{"type":"string"},"description":"Only documents in the API source with this name"},{"in":"query","name":"external_id","schema":{"type":"string"},"description":"Only the document with this external_id (in `source`, or in any API source)"}],"responses":{"200":{"description":"A page of documents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeDocument"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Knowledge"],"summary":"Create or update a knowledge document by external_id","description":"Upsert keyed on `external_id` within the API source (`source`, default \"API\", created on first use): updates that document (200, `created: false`) or creates it (201, `created: true`), and indexes it right away so Pengo Intelligence answers from it. Sending the same content again changes nothing (`result: \"unchanged\"`). Fields left out keep their current value on an update. HTML is converted to text. The text counts against the website's training content; a document that would go past it is a 402 with `details.reason: \"kb_training\"`. At most 120 writes a minute per website. Scope `knowledge:write`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["external_id","title","content"],"additionalProperties":false,"properties":{"external_id":{"type":"string","maxLength":255,"description":"Your id for the document","example":"kb-article-1042"},"title":{"type":"string","maxLength":300},"content":{"type":"string","maxLength":200000,"description":"The document's text, as Markdown or HTML (see `format`)"},"format":{"type":"string","enum":["markdown","html"],"default":"markdown"},"url":{"type":"string","format":"uri","nullable":true},"is_public":{"type":"boolean","default":false,"description":"Answers may link to `url` (only when the audience is public)"},"audience":{"type":"string","enum":["public","verified","internal"],"default":"public"},"channels":{"type":"array","nullable":true,"items":{"type":"string","enum":["chat","email","whatsapp","sms","messenger","instagram"]},"description":"Channels whose answers may use it; null or left out = all"},"language":{"type":"string","nullable":true,"example":"en"},"source":{"type":"string","maxLength":80,"default":"API","description":"The API source to put it in, created on first use"}}}}}},"responses":{"200":{"description":"Existing document updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeDocument"},"created":{"type":"boolean"},"result":{"type":"string","enum":["indexed","unchanged"]}}}}}},"201":{"description":"Document created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeDocument"},"created":{"type":"boolean"},"result":{"type":"string","enum":["indexed","unchanged"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/KnowledgeLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"delete":{"tags":["Knowledge"],"summary":"Remove a knowledge document","description":"By `id`, or by `external_id` (in `source`, default \"API\"). Pengo stops answering from it right away. Scope `knowledge:write`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"in":"query","name":"id","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"external_id","schema":{"type":"string"}},{"in":"query","name":"source","schema":{"type":"string","default":"API"}}],"responses":{"200":{"description":"Document removed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeDocument"},"deleted":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/knowledge/sources":{"get":{"tags":["Knowledge"],"summary":"List the website's API knowledge sources","description":"The sources documents were pushed to, oldest first. A source is created by the first document pushed to its name (\"API\" by default); removing it in Intelligence → Knowledge removes its documents. Scope `knowledge:read`.","parameters":[{"$ref":"#/components/parameters/PropertyId"}],"responses":{"200":{"description":"The API sources","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSource"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/openapi.json":{"get":{"tags":["Meta"],"summary":"This OpenAPI specification","description":"The v1 spec as JSON. No key needed. Generated from the route sources (`npm run openapi`).","security":[],"responses":{"200":{"description":"OpenAPI 3 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tags":{"get":{"tags":["Tags"],"summary":"List conversation tags","description":"The website's tag list (Settings → Tags), by name. Scope `conversations:read`.","parameters":[{"$ref":"#/components/parameters/PropertyId"}],"responses":{"200":{"description":"The website's tags","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/visitors":{"get":{"tags":["Visitors"],"summary":"List visitors","description":"Most recently seen first. Scope `contacts:read`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"in":"query","name":"is_online","schema":{"type":"boolean"}},{"in":"query","name":"has_active_chat","schema":{"type":"boolean"}},{"in":"query","name":"offset","deprecated":true,"schema":{"type":"integer","minimum":0},"description":"Use `cursor` instead. Ignored when `cursor` is set."}],"responses":{"200":{"description":"A page of visitors","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Visitor"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/visitors/{id}":{"get":{"tags":["Visitors"],"summary":"Get a visitor, with their attributes and company","description":"Scope `contacts:read`.","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The visitor, its custom attributes and its company (null when it has none)"},"401":{"description":"Missing or invalid API key"},"404":{"description":"No such visitor on this key's website"}}},"patch":{"tags":["Visitors"],"summary":"Update a visitor's profile and attributes","description":"Scope `contacts:write`. Attributes defined in Settings → Contact data are checked against their type (number, yes/no, date YYYY-MM-DD, list option) and stored typed; a value that doesn't fit returns 422 with the offending keys. Other keys are stored as text; null clears one. A work email links the visitor to its company.\n","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"attributes":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"The updated visitor"},"400":{"description":"Invalid body"},"401":{"description":"Missing or invalid API key"},"404":{"description":"No such visitor on this key's website"},"422":{"description":"An attribute value doesn't fit its definition, or a key is reserved (`error.details` lists them)"}}}},"/api/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","description":"The website's endpoints, without their secrets. Scope `webhooks:read`.","parameters":[{"$ref":"#/components/parameters/PropertyId"}],"responses":{"200":{"description":"The endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Webhooks"],"summary":"Add a webhook endpoint (subscribe)","description":"Subscribe a public https:// URL to events. The answer carries the signing secret once; keep it to verify `X-Pengo-Signature-V2`. Delete the endpoint to unsubscribe (REST hooks, e.g. a Zapier trigger). A website can have up to 10 endpoints, and adding one needs a plan with webhooks. Scope `webhooks:write`.","parameters":[{"$ref":"#/components/parameters/PropertyId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","example":"https://hooks.example.com/pengo"},"events":{"type":"array","minItems":1,"items":{"type":"string"},"example":["message.sent","chat.created"]}}}}}},"responses":{"201":{"description":"Subscribed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string","description":"The signing secret (`whsec_…`), shown only here"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook endpoint","description":"Scope `webhooks:read`.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/PropertyId"}],"responses":{"200":{"description":"The endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook endpoint","description":"Change the URL or events, pause or resume it (`active`), or rotate its secret (`rotate_secret: true`: the new secret is in the answer once, and the previous one keeps signing deliveries for 24 hours). Turning an endpoint back on clears a pause Pengo made after failures, and needs a plan with webhooks. Scope `webhooks:write`.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/PropertyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"rotate_secret":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The updated endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string","description":"After a rotation, the new secret (shown only here)"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint (unsubscribe)","description":"Pengo stops sending events to it at once; deliveries still queued for it are dropped. Scope `webhooks:write`.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/PropertyId"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}