{"openapi":"3.1.0","info":{"title":"Orka API reference","version":"1.0.0","description":"Every route of the Orka REST API, and the payload of every webhook. New here? Start with the guides:\n\n- [Quickstart](/public-api/docs/api/quickstart): create a token and make your first calls\n- [Authentication](/public-api/docs/api/authentication), [Conventions](/public-api/docs/api/conventions) (errors, pagination, idempotency) and [Rate limits](/public-api/docs/api/rate-limits)\n- [Webhooks](/public-api/docs/api/webhooks): setup, signature, retries\n- [Web SDK](/public-api/docs/sdk/install): the chat widget on your site\n\nAll routes need `Authorization: Bearer orka_…`, answer `{ \"data\": … }`, and fail with `{ \"error\": { \"code\", \"message\" } }`."},"servers":[{"url":"https://api.orka.chat","description":"Orka"}],"tags":[{"name":"Token","description":"Check that a token works, and which project it belongs to."},{"name":"Conversations","description":"A conversation is the thread between one visitor and your team. The dashboard calls it a chat."},{"name":"Messages","description":"What is said in a conversation: messages of the visitor, replies of your team and of the AI agent, private notes, system messages."},{"name":"Contacts","description":"The people you talk to, identified by their email. A contact gathers the visitors (browser sessions) of the same person."},{"name":"Events","description":"What happened to a contact in your product. Events show in the timeline your team reads before answering."},{"name":"Visitors","description":"Who is on your site right now, and who is not allowed on it. Live visitors need a plan with the live map."},{"name":"Tags","description":"Labels of conversations."},{"name":"Analytics","description":"Volumes and response times. Needs a plan with analytics."},{"name":"Help center","description":"Collections and articles of your public help center, which the widget and the AI agent also read."},{"name":"Webhook endpoints","description":"Manage where webhooks are sent. The same screen exists in the dashboard, under Settings → Developers."},{"name":"Webhooks","description":"What Orka sends to your webhook endpoints: one entry per event type, with its payload. Setup, signature and retries are in the [Webhooks guide](/public-api/docs/api/webhooks)."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API token of the project, created in the dashboard under Settings → Developers."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable, write your code against it.","example":"validation_error"},"message":{"type":"string","description":"For humans, may change.","example":"Invalid request"},"details":{"description":"With `validation_error`: the invalid fields."}},"required":["code","message"]}},"required":["error"]},"ContactSummary":{"type":["object","null"],"properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"email":{"type":"string","format":"email","example":"ada@example.com"},"email_verified":{"type":"boolean"},"name":{"type":["string","null"],"example":"Ada Lovelace"}},"required":["id","email","email_verified","name"],"description":"`null` while the visitor is anonymous."},"Location":{"type":["object","null"],"properties":{"city":{"type":["string","null"],"example":"Paris"},"country":{"type":["string","null"],"example":"France"},"country_code":{"type":["string","null"],"example":"FR"},"timezone":{"type":["string","null"],"example":"Europe/Paris"}},"required":["city","country","country_code","timezone"]},"Visitor":{"type":"object","properties":{"id":{"type":"string","description":"A visitor is one browser session. The same person on two devices is two visitors, and one contact.","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"contact_id":{"type":["string","null"]},"name":{"type":["string","null"],"example":"Ada Lovelace"},"display_name":{"type":"string","description":"The name shown in Orka: the one of the visitor or their contact, else a name generated for them (`Blue Orca from Paris`).","example":"Ada Lovelace"},"email":{"type":["string","null"],"example":"ada@example.com"},"email_verified":{"type":"boolean","description":"The email of **this session** came from the Web SDK with a valid identity verification signature. This is the one to trust before acting on a request: a verified contact can also be claimed by someone typing its email in the chat, and that session is not verified. Goes back to `false` when the email of the visitor is changed from the dashboard or with `PATCH /conversations/{id}/visitor`."},"avatar_url":{"type":["string","null"],"description":"The photo of the person, null when they have none."},"language":{"type":["string","null"],"example":"fr-FR"},"timezone":{"type":["string","null"],"example":"Europe/Paris"},"platform":{"type":["string","null"],"enum":["desktop","mobile","tablet","tv","bot"]},"browser":{"type":["string","null"],"example":"Chrome 140.0"},"os":{"type":["string","null"],"example":"macOS 15.6"},"location":{"$ref":"#/components/schemas/Location"},"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Attributes of the session, completed by the ones of the contact.","example":{"plan":"pro","mrr":"49"}},"last_pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://acme.com/pricing"},"title":{"type":["string","null"],"example":"Pricing"},"viewed_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["url","title","viewed_at"]},"description":"Newest first, five at most."},"is_blocked":{"type":"boolean"},"last_activity_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","contact_id","name","display_name","email","email_verified","avatar_url","language","timezone","platform","browser","os","location","attributes","last_pages","is_blocked","last_activity_at","created_at"]},"Conversation":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"status":{"type":"string","enum":["open","resolved"]},"subject":{"type":["string","null"],"description":"The first message, unless you set it.","example":"My invoice is wrong"},"contact":{"$ref":"#/components/schemas/ContactSummary"},"visitor":{"$ref":"#/components/schemas/Visitor"},"assignee_id":{"type":["string","null"],"description":"ID of a team member.","example":"64b7f0f0a1b2c3d4e5f6a7b8"},"tags":{"type":"array","items":{"type":"string"},"description":"Tag names.","example":["billing","vip"]},"note":{"type":["string","null"],"description":"Internal note pinned on the conversation."},"ai_enabled":{"type":"boolean","description":"The AI agent answers in this conversation."},"unread_count":{"type":"integer","description":"Messages your team has not read yet."},"messages_count":{"type":"object","properties":{"visitor":{"type":"integer"},"agent":{"type":"integer"},"ai":{"type":"integer"},"bot":{"type":"integer"}},"required":["visitor","agent","ai","bot"]},"last_message":{"type":["object","null"],"properties":{"preview":{"type":"string","description":"First 200 characters.","example":"Thanks, that works!"},"type":{"type":"string","enum":["text","note","attachment","system"]},"author_type":{"type":"string","enum":["visitor","agent","ai","bot"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["preview","type","author_type","created_at"]},"first_message_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"},"last_visitor_message_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"},"last_agent_message_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"},"first_response_seconds":{"type":["integer","null"],"description":"Time your team took to send its first answer.","example":184},"resolved_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"},"resolved_by_id":{"type":["string","null"],"description":"ID of a team member.","example":"64b7f0f0a1b2c3d4e5f6a7b8"},"dashboard_url":{"type":"string","description":"Opens the conversation in Orka.","example":"https://dashboard.orka.chat/rooms/66b1f0a9e4b0a1b2c3d4e5f6"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","status","subject","contact","visitor","assignee_id","tags","note","ai_enabled","unread_count","messages_count","last_message","first_message_at","last_visitor_message_at","last_agent_message_at","first_response_seconds","resolved_at","resolved_by_id","dashboard_url","created_at","updated_at"]},"Pagination":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass it as `cursor` to get the next page. `null` on the last page.","example":"eyJpZCI6IjY2YTAifQ"}},"required":["has_more","next_cursor"]},"Deleted":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]},"Message":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"conversation_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"type":{"type":"string","enum":["text","note","attachment","system"],"description":"`text`: a regular message. `note`: a private note of your team. `attachment`: a file, `content` is its URL. `system`: something that happened, see `system_event`."},"system_event":{"type":["string","null"],"enum":["resolved","reopened","blocked","unblocked","reminder","email_saved","name_saved"],"description":"Set when `type` is `system`, `null` otherwise."},"author":{"type":"object","properties":{"type":{"type":"string","enum":["visitor","agent","ai","bot"],"description":"`agent`: a team member. `ai`: the AI agent. `bot`: automatic messages of Orka."},"id":{"type":["string","null"],"description":"ID of the team member when `type` is `agent`."},"name":{"type":["string","null"],"example":"Olive Owner"}},"required":["type","id","name"]},"content":{"type":"string","example":"Your refund is on its way."},"is_private":{"type":"boolean","description":"`true`: never shown to the visitor (notes, their attachments, reminders)."},"channel":{"type":"string","enum":["chat","email"],"description":"`email`: the visitor was gone, the message reached them by email."},"delivery_status":{"type":"string","enum":["success","pending","bounced"]},"source":{"type":"string","enum":["web","mobile_app","email","api"],"description":"Where it was written. `web`: the widget or the dashboard. `email`: a reply by email. `api`: your back end, and the system messages the dashboard records the same way (resolved, reminder)."},"page":{"type":["object","null"],"properties":{"url":{"type":"string"},"title":{"type":["string","null"]}},"required":["url","title"],"description":"Page the visitor was on."},"translations":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string","example":"en"},"content":{"type":"string"}},"required":["language","content"]}},"is_edited":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","conversation_id","type","system_event","author","content","is_private","channel","delivery_status","source","page","translations","is_edited","created_at","updated_at"]},"Contact":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"email":{"type":"string","format":"email","example":"ada@example.com"},"email_verified":{"type":"boolean","description":"`true` when the email is known to belong to this person: the Web SDK sent it with a valid identity verification signature, or your back end wrote the contact through `POST /contacts` or `POST /events`. `false` for an email typed in the chat, sent unsigned, or given to `POST /conversations`."},"name":{"type":["string","null"],"example":"Ada Lovelace"},"display_name":{"type":"string","description":"What the dashboard shows: the name, or the start of the email.","example":"Ada Lovelace"},"avatar_url":{"type":["string","null"],"description":"The photo of the person, null when they have none."},"is_blocked":{"type":"boolean"},"language":{"type":["string","null"],"description":"Browser language of the last visit.","example":"fr-FR"},"location":{"allOf":[{"$ref":"#/components/schemas/Location"},{"description":"From the IP address of the last visit."}]},"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom attributes. Values are strings.","example":{"plan":"pro","mrr":"49"}},"last_seen_at":{"type":["string","null"],"format":"date-time","description":"Last page viewed with the widget loaded. `null` for a contact who never did.","example":"2026-09-21T14:03:12.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","email","email_verified","name","display_name","avatar_url","is_blocked","language","location","attributes","last_seen_at","created_at","updated_at"]},"ContactNote":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"content":{"type":"string"},"author_id":{"type":["string","null"],"description":"ID of a team member.","example":"64b7f0f0a1b2c3d4e5f6a7b8"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","content","author_id","created_at","updated_at"]},"Event":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"contact_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"name":{"type":"string","example":"Subscription upgraded"},"data":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"example":{"from":"starter","to":"pro"}},"color":{"type":"string","enum":["grey","green","blue","orange","red","purple"]},"source":{"type":"string","enum":["api","sdk"],"description":"`api`: sent by your back end. `sdk`: sent from the browser, anyone can forge it."},"occurred_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","contact_id","name","data","color","source","occurred_at","created_at"]},"BlockRule":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"type":{"type":"string","enum":["ip","country"]},"value":{"type":"string","example":"203.0.113.7"},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","type","value","created_at"]},"Tag":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"name":{"type":"string","example":"billing"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","name","created_at"]},"Analytics":{"type":"object","properties":{"from":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"to":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"conversations":{"type":"object","properties":{"started":{"type":"integer","description":"Conversations of visitors who arrived in the period."},"resolved":{"type":"integer","description":"Conversations resolved in the period, and still resolved."}},"required":["started","resolved"]},"messages":{"type":"object","properties":{"visitor":{"type":"integer"},"agent":{"type":"integer"},"ai":{"type":"integer"},"bot":{"type":"integer"}},"required":["visitor","agent","ai","bot"],"description":"Messages sent in the period, private notes excluded."},"average_first_response_seconds":{"type":["integer","null"]},"average_resolution_seconds":{"type":["integer","null"]},"new_contacts":{"type":"integer"},"new_visitors":{"type":"integer"}},"required":["from","to","conversations","messages","average_first_response_seconds","average_resolution_seconds","new_contacts","new_visitors"]},"HelpCollection":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"parent_id":{"type":["string","null"],"description":"Set for a section of another collection."},"name":{"type":"string","example":"Getting started"},"slug":{"type":"string","example":"getting-started"},"description":{"type":["string","null"]},"icon":{"type":["string","null"],"example":"🚀"},"order":{"type":"integer"},"articles_count":{"type":"integer"},"published_articles_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","parent_id","name","slug","description","icon","order","articles_count","published_articles_count","created_at","updated_at"]},"HelpArticleSummary":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"collection_id":{"type":["string","null"]},"title":{"type":"string","example":"Install the widget"},"slug":{"type":"string","example":"install-the-widget"},"icon":{"type":["string","null"]},"description":{"type":["string","null"]},"state":{"type":"string","enum":["draft","suggested","published"]},"meta_title":{"type":["string","null"]},"meta_description":{"type":["string","null"]},"author_id":{"type":["string","null"],"description":"ID of a team member.","example":"64b7f0f0a1b2c3d4e5f6a7b8"},"order":{"type":"integer"},"views":{"type":"integer"},"reactions":{"type":"object","properties":{"happy":{"type":"integer"},"neutral":{"type":"integer"},"sad":{"type":"integer"}},"required":["happy","neutral","sad"]},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the article is translated into.","example":["fr","de"]},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","collection_id","title","slug","icon","description","state","meta_title","meta_description","author_id","order","views","reactions","languages","published_at","created_at","updated_at"]},"HelpArticle":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"collection_id":{"type":["string","null"]},"title":{"type":"string","example":"Install the widget"},"slug":{"type":"string","example":"install-the-widget"},"icon":{"type":["string","null"]},"description":{"type":["string","null"]},"state":{"type":"string","enum":["draft","suggested","published"]},"meta_title":{"type":["string","null"]},"meta_description":{"type":["string","null"]},"author_id":{"type":["string","null"],"description":"ID of a team member.","example":"64b7f0f0a1b2c3d4e5f6a7b8"},"order":{"type":"integer"},"views":{"type":"integer"},"reactions":{"type":"object","properties":{"happy":{"type":"integer"},"neutral":{"type":"integer"},"sad":{"type":"integer"}},"required":["happy","neutral","sad"]},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the article is translated into.","example":["fr","de"]},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"body_markdown":{"type":"string","example":"# Install the widget\n\nPaste **the snippet** before `</head>`."},"body_html":{"type":"string","description":"Sanitized HTML rendered from the Markdown, what readers see."}},"required":["id","collection_id","title","slug","icon","description","state","meta_title","meta_description","author_id","order","views","reactions","languages","published_at","created_at","updated_at","body_markdown","body_html"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"name":{"type":"string","example":"CRM sync"},"url":{"type":"string","example":"https://api.example.com/webhooks/orka"},"events":{"type":"array","items":{"type":"string","enum":["conversation.created","conversation.identified","conversation.assigned","conversation.resolved","conversation.reopened","message.created","contact.created","contact.updated"]}},"is_active":{"type":"boolean","description":"`false` when you paused it, or after 3 days of failed deliveries."},"disabled_reason":{"type":["string","null"],"enum":["manual","too_many_failures"]},"secret_prefix":{"type":"string","description":"First characters of the signing secret, to tell endpoints apart.","example":"whsec_4fK2"},"last_delivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["success","failed"]},"http_status":{"type":["integer","null"]},"at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["status","http_status","at"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","name","url","events","is_active","disabled_reason","secret_prefix","last_delivery","created_at","updated_at"]},"WebhookEndpointWithSecret":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string","description":"Signing secret. **Returned once, at creation.**","example":"whsec_4fK2vR8sYw1ZqLm3Tn6Bc9XdPq7Ha2Ue"}},"required":["secret"]}]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"endpoint_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"event_id":{"type":"string","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"event_type":{"type":"string","example":"message.created"},"status":{"type":"string","enum":["pending","success","failed","canceled"],"description":"`pending`: not sent yet, or waiting for a retry. `failed`: every attempt failed. `canceled`: the endpoint was paused or disabled."},"attempts":{"type":"integer"},"http_status":{"type":["integer","null"],"description":"Status of the last attempt. `null` when your server could not be reached."},"response":{"type":["string","null"],"description":"First 500 characters your server answered, or the network error."},"duration_ms":{"type":["integer","null"]},"last_attempt_at":{"type":["string","null"],"format":"date-time","example":"2026-09-21T14:03:12.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"}},"required":["id","endpoint_id","event_id","event_type","status","attempts","http_status","response","duration_ms","last_attempt_at","created_at"]}},"parameters":{}},"paths":{"/public-api/v1/ping":{"get":{"security":[{"BearerAuth":[]}],"summary":"Check a token","description":"Returns the project the token belongs to. Use it to test your setup, it changes nothing.","tags":["Token"],"responses":{"200":{"description":"The token is valid.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"project_name":{"type":"string","example":"Acme"},"token_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"}},"required":["project_id","project_name","token_id"]}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations":{"get":{"security":[{"BearerAuth":[]}],"summary":"List conversations","description":"Conversations with at least one message, in the order of the inbox. A visitor who loaded the widget without writing has no conversation.\n\nFor an incremental sync, keep the date of your last run and pass it as `updated_since`.","tags":["Conversations"],"parameters":[{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Number of results per page, from 1 to 100.","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"`pagination.next_cursor` of the previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["open","resolved"],"description":"Omit to get both."},"required":false,"name":"status","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$"},{"type":"string","enum":["none"]}],"description":"ID of a team member, or `none` for unassigned conversations."},"required":false,"name":"assignee_id","in":"query"},{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":false,"name":"contact_id","in":"query"},{"schema":{"type":"string","maxLength":254,"format":"email","description":"Conversations of the contact with this email."},"required":false,"name":"email","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":60},"description":"Tag names, comma-separated. Conversations with at least one of them."},"required":false,"name":"tag","in":"query"},{"schema":{"type":["boolean","null"],"description":"`true`: only the conversations with messages your team has not read."},"required":false,"name":"unread","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Conversations updated at or after this date. Use it for incremental syncs."},"required":false,"name":"updated_since","in":"query"},{"schema":{"type":"string","enum":["-last_message_at","last_message_at","-id","id"],"default":"-last_message_at","description":"Prefix with `-` for descending. `-last_message_at` *(default)* is the order of the inbox."},"required":false,"name":"sort","in":"query"}],"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"}},"required":["data","pagination"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Start a conversation","description":"Creates a conversation in the name of a person who wrote to you somewhere else: a contact form, a feedback box in your app, an import. `content` becomes the first message, written by that person. Your team answers from the inbox, and the answer reaches the person by email.\n\nThe contact of this email is created when it does not exist. If the AI agent is on, it may answer.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Makes the request safe to retry, see [Idempotency](/public-api/docs/api/conventions#idempotency).","example":"0b9c2f6e-6f0a-4a6e-9d0b-1f6a3c1f2b77"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email of the person. The contact is created when it does not exist."},"name":{"type":"string","minLength":1,"maxLength":120},"content":{"type":"string","minLength":1,"maxLength":10000,"description":"First message, written by the person."},"subject":{"type":"string","maxLength":200},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Custom attributes, the same ones the Web SDK sets with `Orka.update()`. Keys are merged with the existing ones. Values are stored as strings. `null` removes the key.","example":{"plan":"pro","mrr":"49","trial_ends_at":null}},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":20,"description":"Tag names. Unknown tags are created."},"page":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","pattern":"^https?:\\/\\/"},"title":{"type":"string","maxLength":300}},"required":["url"],"description":"Where the message was written, a contact form for instance."}},"required":["email","content"],"additionalProperties":false}}}},"responses":{"201":{"description":"Conversation created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: the resource already exists. `idempotency_conflict`: the `Idempotency-Key` was used with another body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/batch":{"post":{"security":[{"BearerAuth":[]}],"summary":"Update many conversations","description":"Resolves, reopens or marks as read up to 100 conversations. IDs that are not conversations of the project are returned in `not_found`, the others are processed.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Makes the request safe to retry, see [Idempotency](/public-api/docs/api/conventions#idempotency).","example":"0b9c2f6e-6f0a-4a6e-9d0b-1f6a3c1f2b77"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"},"minItems":1,"maxItems":100,"description":"Conversation IDs, 100 at most."},"action":{"type":"string","enum":["resolve","reopen","read"]},"member_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Team member credited for `resolve` and `reopen`. Defaults to the project owner."}},"required":["ids","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"What was done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"action":{"type":"string","enum":["resolve","reopen","read"]},"updated":{"type":"array","items":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"}},"not_found":{"type":"array","items":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"}}},"required":["action","updated","not_found"]}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: the resource already exists. `idempotency_conflict`: the `Idempotency-Key` was used with another body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}":{"get":{"security":[{"BearerAuth":[]}],"summary":"Get a conversation","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The conversation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"security":[{"BearerAuth":[]}],"summary":"Update a conversation","description":"Resolve or reopen, assign, tag, pin a note, switch the AI agent on or off. Only the fields you send change. Each change does what it does from the dashboard: the inbox updates live, a system message records a resolution, the matching webhook fires.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","resolved"]},"assignee_id":{"type":["string","null"],"pattern":"^[a-f0-9]{24}$","description":"ID of a team member. `null` unassigns."},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":20,"description":"Replaces the tags of the conversation. Unknown tags are created."},"subject":{"type":["string","null"],"maxLength":200},"note":{"type":["string","null"],"maxLength":5000,"description":"Internal note pinned on the conversation, never shown to the visitor."},"ai_enabled":{"type":"boolean","description":"Lets the AI agent answer in this conversation, or stops it."},"resolved_by_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"With `status: resolved`: the team member credited. Defaults to the project owner."}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated conversation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete a conversation","description":"Deletes the messages of the conversation, which leaves the inbox and the API. **This cannot be undone.** The visitor keeps a working widget: their next message starts a new conversation. The files sent as attachments are deleted too.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Conversation deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}/visitor":{"patch":{"security":[{"BearerAuth":[]}],"summary":"Update the visitor of a conversation","description":"Name, email, custom attributes and blocking of the person in the conversation. Setting an `email` links the visitor to the contact of this email, created when needed, and fires `conversation.identified`.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","maxLength":254,"format":"email","description":"Links the visitor to the contact with this email, created when it does not exist."},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Custom attributes, the same ones the Web SDK sets with `Orka.update()`. Keys are merged with the existing ones. Values are stored as strings. `null` removes the key.","example":{"plan":"pro","mrr":"49","trial_ends_at":null}},"is_blocked":{"type":"boolean","description":"A blocked visitor cannot use the widget anymore."}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated conversation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}/read":{"post":{"security":[{"BearerAuth":[]}],"summary":"Mark as read","description":"Marks every message as read by your team: `unread_count` goes back to 0, in the inbox too.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The updated conversation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}/unread":{"post":{"security":[{"BearerAuth":[]}],"summary":"Mark as unread","description":"Puts the conversation back in the unread ones of the inbox.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The updated conversation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}/transcript":{"post":{"security":[{"BearerAuth":[]}],"summary":"Send the transcript by email","description":"Limited to 20 per hour and per project.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Where to send the transcript. Defaults to the email of the visitor."}},"additionalProperties":false}}}},"responses":{"202":{"description":"The email is queued.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sent_to":{"type":"string","format":"email"}},"required":["sent_to"]}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}/reminders":{"post":{"security":[{"BearerAuth":[]}],"summary":"Set a reminder","description":"Reminds a team member about the conversation later, by email and notification. The conversation shows the reminder to your team, not to the visitor.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Makes the request safe to retry, see [Idempotency](/public-api/docs/api/conventions#idempotency).","example":"0b9c2f6e-6f0a-4a6e-9d0b-1f6a3c1f2b77"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"remind_at":{"type":"string","format":"date-time","description":"When to remind. In the future, one year ahead at most."},"note":{"type":"string","maxLength":500},"member_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Team member to remind. Defaults to the project owner."}},"required":["remind_at"],"additionalProperties":false}}}},"responses":{"201":{"description":"Reminder set.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"remind_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"note":{"type":["string","null"]},"member_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"}},"required":["id","remind_at","note","member_id"]}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: the resource already exists. `idempotency_conflict`: the `Idempotency-Key` was used with another body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`: a part of Orka this needs does not answer right now, try again in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}/typing":{"post":{"security":[{"BearerAuth":[]}],"summary":"Show a typing indicator","description":"Shows the three dots of a team member in the widget. Call it again every few seconds while your integration prepares its answer, the widget drops the indicator by itself. Sending the message removes it.","tags":["Conversations"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"is_typing":{"type":"boolean","default":true},"member_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Team member shown as typing. Defaults to the project owner."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Sent to the widget.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"is_typing":{"type":"boolean"}},"required":["is_typing"]}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}/messages":{"get":{"security":[{"BearerAuth":[]}],"summary":"List the messages of a conversation","description":"Oldest first by default. **Private notes are included**: filter on `is_private` before showing messages to anyone outside your team.","tags":["Messages"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Number of results per page, from 1 to 100.","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"`pagination.next_cursor` of the previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["text","note","attachment","system"]},"description":"Comma-separated. Omit to get every type."},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["id","-id"],"default":"id","description":"`id` *(default)*: oldest first, the reading order. `-id`: newest first."},"required":false,"name":"sort","in":"query"}],"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"}},"required":["data","pagination"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Send a message","description":"Replies to the visitor as a team member, or leaves a private note. The message shows up live in the widget and in the inbox, like one written from the dashboard. If the visitor is gone and left an email, they get it by email after a moment.\n\nA reply assigns the conversation to its author. Messages are always written as your team: the only message of a visitor the API creates is the first one of `POST /conversations`.","tags":["Messages"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Makes the request safe to retry, see [Idempotency](/public-api/docs/api/conventions#idempotency).","example":"0b9c2f6e-6f0a-4a6e-9d0b-1f6a3c1f2b77"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":10000,"description":"Plain text. Markdown links and line breaks are kept."},"type":{"type":"string","enum":["text","note"],"default":"text","description":"`text`: a reply the visitor sees. `note`: a private note only your team sees."},"author_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Team member the message is written as. Defaults to the project owner."}},"required":["content"],"additionalProperties":false}}}},"responses":{"201":{"description":"Message created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: the resource already exists. `idempotency_conflict`: the `Idempotency-Key` was used with another body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/conversations/{id}/messages/{message_id}":{"get":{"security":[{"BearerAuth":[]}],"summary":"Get a message","tags":["Messages"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"message_id","in":"path"}],"responses":{"200":{"description":"The message.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"security":[{"BearerAuth":[]}],"summary":"Edit a message","description":"Text messages and notes written by your team or by the AI agent, **for 15 minutes**, like in the dashboard: after that the visitor has read the message, or received it by email. The widget shows the edit live, with an *edited* mark.","tags":["Messages"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"message_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":10000}},"required":["content"],"additionalProperties":false}}}},"responses":{"200":{"description":"The edited message.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete a message","description":"Same rule as the edit: messages of your team or of the AI agent, for 15 minutes. Attachments sent by your team can be deleted at any time, their file is deleted with them.","tags":["Messages"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"message_id","in":"path"}],"responses":{"200":{"description":"Message deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/contacts":{"get":{"security":[{"BearerAuth":[]}],"summary":"List contacts","description":"A contact is a person with an email. Visitors who never left one are not contacts.","tags":["Contacts"],"parameters":[{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Number of results per page, from 1 to 100.","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"`pagination.next_cursor` of the previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","maxLength":254,"format":"email","description":"Exact match. The way to find a contact from your own user."},"required":false,"name":"email","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":120,"description":"Searches names and emails."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"updated_since","in":"query"},{"schema":{"type":"string","enum":["-last_seen_at","last_seen_at","-id","id"],"default":"-id","description":"`-id` *(default)*: most recently created first."},"required":false,"name":"sort","in":"query"}],"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"}},"required":["data","pagination"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Create or update a contact","description":"An upsert on the email: creates the contact, or updates the one that has this email. Call it when a user signs up or changes plan, without checking first whether the contact exists. Attributes are merged with the existing ones, fields you do not send are kept.","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email"},"name":{"type":"string","minLength":1,"maxLength":120},"avatar_url":{"type":"string","maxLength":2000,"format":"uri"},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Custom attributes, the same ones the Web SDK sets with `Orka.update()`. Keys are merged with the existing ones. Values are stored as strings. `null` removes the key.","example":{"plan":"pro","mrr":"49","trial_ends_at":null}}},"required":["email"],"additionalProperties":false}}}},"responses":{"200":{"description":"The contact existed, it was updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}},"required":["data"]}}}},"201":{"description":"Contact created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/contacts/stats":{"get":{"security":[{"BearerAuth":[]}],"summary":"Count contacts","tags":["Contacts"],"responses":{"200":{"description":"Numbers of the project.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"online":{"type":"integer","description":"Contacts with the widget open right now."}},"required":["total","online"]}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/contacts/{id}":{"get":{"security":[{"BearerAuth":[]}],"summary":"Get a contact","tags":["Contacts"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The contact.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"security":[{"BearerAuth":[]}],"summary":"Update a contact","description":"Blocking a contact blocks every browser they used.","tags":["Contacts"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"`409 conflict` when another contact already has this email."},"name":{"type":["string","null"],"minLength":1,"maxLength":120},"avatar_url":{"type":["string","null"],"maxLength":2000,"format":"uri"},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Custom attributes, the same ones the Web SDK sets with `Orka.update()`. Keys are merged with the existing ones. Values are stored as strings. `null` removes the key.","example":{"plan":"pro","mrr":"49","trial_ends_at":null}},"is_blocked":{"type":"boolean","description":"A blocked contact cannot load the widget."}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated contact.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: the resource already exists. `idempotency_conflict`: the `Idempotency-Key` was used with another body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete a contact","description":"Deletes the contact **with their conversations, messages, notes and events**. This is the erasure request of the GDPR, it cannot be undone.","tags":["Contacts"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Contact deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/contacts/{id}/conversations":{"get":{"security":[{"BearerAuth":[]}],"summary":"List the conversations of a contact","description":"Every conversation of the person, across their devices. Most recent first.","tags":["Contacts"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Number of results per page, from 1 to 100.","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"`pagination.next_cursor` of the previous page."},"required":false,"name":"cursor","in":"query"}],"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"}},"required":["data","pagination"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/contacts/{id}/notes":{"get":{"security":[{"BearerAuth":[]}],"summary":"List the notes of a contact","tags":["Contacts"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Notes, most recent first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactNote"}}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Add a note to a contact","description":"Notes are internal: the person never sees them. Handy to push context from your CRM.","tags":["Contacts"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Makes the request safe to retry, see [Idempotency](/public-api/docs/api/conventions#idempotency).","example":"0b9c2f6e-6f0a-4a6e-9d0b-1f6a3c1f2b77"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":5000},"author_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Team member the note is written as. Defaults to the project owner."}},"required":["content"],"additionalProperties":false}}}},"responses":{"201":{"description":"Note created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContactNote"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: the resource already exists. `idempotency_conflict`: the `Idempotency-Key` was used with another body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/contacts/{id}/notes/{note_id}":{"patch":{"security":[{"BearerAuth":[]}],"summary":"Edit a note","tags":["Contacts"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"note_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":5000}},"required":["content"],"additionalProperties":false}}}},"responses":{"200":{"description":"The edited note.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContactNote"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete a note","tags":["Contacts"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"note_id","in":"path"}],"responses":{"200":{"description":"Note deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/events":{"post":{"security":[{"BearerAuth":[]}],"summary":"Track an event","description":"Adds an event to the timeline of a contact: \"Subscription upgraded\", \"Payment failed\", \"Churned\". Your team sees it next to the conversation, between the pages the person visited.\n\nTarget the contact with `email` or `contact_id`. With an unknown `email` the contact is created: you can track events for users who never opened the chat.","tags":["Events"],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Makes the request safe to retry, see [Idempotency](/public-api/docs/api/conventions#idempotency).","example":"0b9c2f6e-6f0a-4a6e-9d0b-1f6a3c1f2b77"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","description":"Email of the contact. The contact is created when it does not exist."},"contact_id":{"type":"string","pattern":"^[a-f0-9]{24}$"},"name":{"type":"string","minLength":1,"maxLength":120,"description":"What happened, as your team will read it.","example":"Subscription upgraded"},"data":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Details shown under the event.","example":{"from":"starter","to":"pro","amount":49}},"color":{"type":"string","enum":["grey","green","blue","orange","red","purple"],"default":"grey","description":"Color of the event in the timeline."},"occurred_at":{"type":"string","format":"date-time","description":"Defaults to now. Set it to import past events."}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Event created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Event"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: the resource already exists. `idempotency_conflict`: the `Idempotency-Key` was used with another body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/contacts/{id}/events":{"get":{"security":[{"BearerAuth":[]}],"summary":"List the events of a contact","description":"Most recent first.","tags":["Events"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Number of results per page, from 1 to 100.","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"`pagination.next_cursor` of the previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":120,"description":"Exact match on the event name."},"required":false,"name":"name","in":"query"}],"responses":{"200":{"description":"A page of events.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/events/{id}":{"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete an event","tags":["Events"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Event deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/visitors/online":{"get":{"security":[{"BearerAuth":[]}],"summary":"List the visitors online","description":"Who has the widget open right now, most recently active first: the live map of the dashboard. `total` is the number of visitors online, which can exceed the page.","tags":["Visitors"],"parameters":[{"schema":{"type":["integer","null"],"minimum":1,"maximum":200,"description":"From 1 to 200.","example":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Visitors online.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Visitor"}},"total":{"type":"integer"}},"required":["data","total"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`: a part of Orka this needs does not answer right now, try again in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/visitors/online/count":{"get":{"security":[{"BearerAuth":[]}],"summary":"Count the visitors online","tags":["Visitors"],"responses":{"200":{"description":"Number of visitors with the widget open.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`: a part of Orka this needs does not answer right now, try again in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/block-rules":{"get":{"security":[{"BearerAuth":[]}],"summary":"List block rules","description":"IP addresses and countries that cannot load the widget. To block one person, use `is_blocked` on their contact or on the visitor of a conversation.","tags":["Visitors"],"responses":{"200":{"description":"Every rule of the project.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BlockRule"}}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Block an IP address or a country","tags":["Visitors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["ip","country"]},"value":{"type":"string","minLength":2,"maxLength":45,"description":"An IP address, or an ISO 3166-1 alpha-2 country code.","example":"203.0.113.7"}},"required":["type","value"],"additionalProperties":false}}}},"responses":{"200":{"description":"The rule already existed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BlockRule"}},"required":["data"]}}}},"201":{"description":"Rule created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BlockRule"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/block-rules/{id}":{"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete a block rule","tags":["Visitors"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Rule deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/tags":{"get":{"security":[{"BearerAuth":[]}],"summary":"List tags","tags":["Tags"],"responses":{"200":{"description":"Every tag of the project, in alphabetical order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Create a tag","description":"Not needed before tagging: `PATCH /conversations/{id}` creates the tags it does not know.","tags":["Tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Tag created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tag"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: the resource already exists. `idempotency_conflict`: the `Idempotency-Key` was used with another body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/tags/{id}":{"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete a tag","description":"Removes the tag from every conversation that has it.","tags":["Tags"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Tag deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/analytics":{"get":{"security":[{"BearerAuth":[]}],"summary":"Get the numbers of a period","description":"Volumes and response times, over the last 30 days by default.","tags":["Analytics"],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of the period. Defaults to 30 days ago."},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the period. Defaults to now. A period covers one year at most."},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"The numbers of the period.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Analytics"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/help-center/collections":{"get":{"security":[{"BearerAuth":[]}],"summary":"List collections","description":"Collections and their sections (`parent_id`), in display order. Not paginated: a help center has 100 collections at most.","tags":["Help center"],"responses":{"200":{"description":"Every collection.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HelpCollection"}}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Create a collection","description":"Added after the existing ones. When the help center has several languages, the name and the description are translated right away.","tags":["Help center"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"icon":{"type":"string","maxLength":16},"slug":{"type":"string","minLength":1,"maxLength":200},"parent_id":{"type":["string","null"],"pattern":"^[a-f0-9]{24}$","description":"Makes the collection a section of another one. One level of nesting."}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Collection created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HelpCollection"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/help-center/collections/{id}":{"patch":{"security":[{"BearerAuth":[]}],"summary":"Update a collection","tags":["Help center"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"icon":{"type":"string","maxLength":16},"slug":{"type":"string","minLength":1,"maxLength":200},"parent_id":{"type":["string","null"],"pattern":"^[a-f0-9]{24}$","description":"Makes the collection a section of another one. One level of nesting."}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated collection.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HelpCollection"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete a collection","description":"Its articles are kept, without collection: they leave the public site until you move them. Its sections become collections.","tags":["Help center"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Collection deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/help-center/articles":{"get":{"security":[{"BearerAuth":[]}],"summary":"List articles","description":"Most recently created first, without their body.","tags":["Help center"],"parameters":[{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Number of results per page, from 1 to 100.","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"`pagination.next_cursor` of the previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$"},{"type":"string","enum":["none"]}],"description":"`none`: articles without collection."},"required":false,"name":"collection_id","in":"query"},{"schema":{"type":"string","enum":["draft","suggested","published"],"description":"`suggested`: drafts written by the AI, waiting for a review."},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Searches titles and descriptions."},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"A page of articles.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HelpArticleSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Create an article","description":"Written in Markdown. A draft by default: send `state: published` to put it online. Handy to keep your help center in sync with docs you write somewhere else.","tags":["Help center"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"body_markdown":{"type":"string","maxLength":204800,"description":"The article, in Markdown. The HTML shown to readers is rendered from it."},"description":{"type":"string","maxLength":500},"icon":{"type":"string","maxLength":16,"description":"An emoji shown before the title."},"collection_id":{"type":["string","null"],"pattern":"^[a-f0-9]{24}$","description":"An article without collection is not listed on the public site."},"state":{"type":"string","enum":["draft","published"]},"slug":{"type":"string","minLength":1,"maxLength":200,"description":"Made unique when already taken. Defaults to the title."},"meta_title":{"type":"string","maxLength":120},"meta_description":{"type":"string","maxLength":320},"order":{"type":"integer","minimum":0}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"Article created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HelpArticle"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/help-center/articles/{id}":{"get":{"security":[{"BearerAuth":[]}],"summary":"Get an article","tags":["Help center"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The article, with its body.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HelpArticle"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"security":[{"BearerAuth":[]}],"summary":"Update an article","description":"The slug follows the title until the first publication, then stays: a published URL does not change by itself.","tags":["Help center"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"body_markdown":{"type":"string","maxLength":204800,"description":"The article, in Markdown. The HTML shown to readers is rendered from it."},"description":{"type":"string","maxLength":500},"icon":{"type":"string","maxLength":16,"description":"An emoji shown before the title."},"collection_id":{"type":["string","null"],"pattern":"^[a-f0-9]{24}$","description":"An article without collection is not listed on the public site."},"state":{"type":"string","enum":["draft","published"]},"slug":{"type":"string","minLength":1,"maxLength":200,"description":"Made unique when already taken. Defaults to the title."},"meta_title":{"type":"string","maxLength":120},"meta_description":{"type":"string","maxLength":320},"order":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated article.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HelpArticle"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete an article","description":"With its translations and its images.","tags":["Help center"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Article deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`: a part of Orka this needs does not answer right now, try again in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/webhook-endpoints":{"get":{"security":[{"BearerAuth":[]}],"summary":"List webhook endpoints","tags":["Webhook endpoints"],"responses":{"200":{"description":"Every endpoint of the project.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"BearerAuth":[]}],"summary":"Create a webhook endpoint","description":"The response is the only time the signing `secret` is returned. 10 endpoints per project at most.","tags":["Webhook endpoints"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"url":{"type":"string","maxLength":2000,"format":"uri","description":"Public HTTPS URL. Private and local addresses are refused.","example":"https://api.example.com/webhooks/orka"},"events":{"type":"array","items":{"type":"string","enum":["conversation.created","conversation.identified","conversation.assigned","conversation.resolved","conversation.reopened","message.created","contact.created","contact.updated"]},"minItems":1,"description":"Event types sent to this endpoint."}},"required":["name","url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"Endpoint created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/webhook-endpoints/{id}":{"get":{"security":[{"BearerAuth":[]}],"summary":"Get a webhook endpoint","tags":["Webhook endpoints"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"security":[{"BearerAuth":[]}],"summary":"Update a webhook endpoint","description":"`is_active: false` pauses it: its pending deliveries are canceled, nothing is sent. `is_active: true` enables it again, also after Orka disabled it.","tags":["Webhook endpoints"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"url":{"type":"string","maxLength":2000,"format":"uri","description":"Public HTTPS URL. Private and local addresses are refused.","example":"https://api.example.com/webhooks/orka"},"events":{"type":"array","items":{"type":"string","enum":["conversation.created","conversation.identified","conversation.assigned","conversation.resolved","conversation.reopened","message.created","contact.created","contact.updated"]},"minItems":1,"description":"Event types sent to this endpoint."},"is_active":{"type":"boolean","description":"`true` re-enables an endpoint disabled after repeated failures."}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}},"required":["data"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`unprocessable`: the request is valid but cannot be carried out, the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"security":[{"BearerAuth":[]}],"summary":"Delete a webhook endpoint","description":"With its delivery log. Pending retries are dropped.","tags":["Webhook endpoints"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Endpoint deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/webhook-endpoints/{id}/ping":{"post":{"security":[{"BearerAuth":[]}],"summary":"Send a test event","description":"Sends a `webhook.ping` event to the endpoint right away, signed like a real one, and tells what your server answered. Not retried.","tags":["Webhook endpoints"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The ping was sent. `delivered` says whether your server answered with a 2xx.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"event_id":{"type":"string"},"delivered":{"type":"boolean"},"http_status":{"type":["integer","null"]},"response":{"type":["string","null"]},"duration_ms":{"type":"integer"}},"required":["event_id","delivered","http_status","response","duration_ms"]}},"required":["data"]}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-api/v1/webhook-endpoints/{id}/deliveries":{"get":{"security":[{"BearerAuth":[]}],"summary":"List the deliveries of an endpoint","description":"What was sent to the endpoint and what your server answered, most recent first. Kept 30 days.","tags":["Webhook endpoints"],"parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Number of results per page, from 1 to 100.","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"`pagination.next_cursor` of the previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["pending","success","failed","canceled"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"A page of deliveries.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"`validation_error`: a parameter is missing or invalid, `details` says which one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: missing, malformed, unknown or revoked token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_not_eligible`: the plan of the project does not include this. `project_inactive`: the project was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the resource does not exist in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`: wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"conversation.created":{"post":{"summary":"conversation.created","description":"The first message of a conversation was sent. Loading the widget without writing fires nothing. `data.contact` is already set when the SDK identified the visitor.","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["conversation.created"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["conversation.created"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"$ref":"#/components/schemas/Conversation"}},"required":["id","type","created_at","project_id","data"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}},"conversation.identified":{"post":{"summary":"conversation.identified","description":"The visitor of an ongoing conversation got an email, typed in the chat, sent by the SDK or set by your team, and is now linked to a contact: `data.contact` is set. Fires for new and for existing contacts. **This is the event to plug into your CRM**, together with `conversation.created` for the visitors who were identified before they wrote.","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["conversation.identified"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["conversation.identified"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"$ref":"#/components/schemas/Conversation"}},"required":["id","type","created_at","project_id","data"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}},"conversation.assigned":{"post":{"summary":"conversation.assigned","description":"The conversation was assigned to a team member, by hand or because they answered, or unassigned (`data.assignee_id` is `null`).","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["conversation.assigned"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["conversation.assigned"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"$ref":"#/components/schemas/Conversation"},"previous":{"type":"object","properties":{"assignee_id":{"type":["string","null"]}},"required":["assignee_id"],"description":"Values before the change."}},"required":["id","type","created_at","project_id","data","previous"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}},"conversation.resolved":{"post":{"summary":"conversation.resolved","description":"The conversation was marked as resolved, from the dashboard, the mobile app or the API.","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["conversation.resolved"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["conversation.resolved"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"$ref":"#/components/schemas/Conversation"}},"required":["id","type","created_at","project_id","data"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}},"conversation.reopened":{"post":{"summary":"conversation.reopened","description":"A resolved conversation is open again: a team member reopened it, or the visitor wrote again.","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["conversation.reopened"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["conversation.reopened"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"$ref":"#/components/schemas/Conversation"}},"required":["id","type","created_at","project_id","data"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}},"message.created":{"post":{"summary":"message.created","description":"A message was added to a conversation, whoever wrote it: check `data.author.type`. Private notes fire it too, with `data.is_private: true`. System messages do not, the `conversation.*` events cover them.","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["message.created"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["message.created"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"$ref":"#/components/schemas/Message"}},"required":["id","type","created_at","project_id","data"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}},"contact.created":{"post":{"summary":"contact.created","description":"A contact was created: a visitor left their email, the SDK identified them, or your back end called the API.","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["contact.created"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["contact.created"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"$ref":"#/components/schemas/Contact"}},"required":["id","type","created_at","project_id","data"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}},"contact.updated":{"post":{"summary":"contact.updated","description":"The email, the name, the avatar, the attributes or the blocked state of a contact changed. Page views do not fire it.","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["contact.updated"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["contact.updated"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"$ref":"#/components/schemas/Contact"}},"required":["id","type","created_at","project_id","data"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}},"webhook.ping":{"post":{"summary":"webhook.ping","description":"A test event, sent by the **Test** button of the dashboard or by `POST /webhook-endpoints/{id}/ping`.","tags":["Webhooks"],"security":[],"parameters":[{"schema":{"type":"string","description":"Same as `id` in the body. Reused when the delivery is retried."},"required":true,"name":"X-Orka-Event-Id","in":"header"},{"schema":{"type":"string","enum":["webhook.ping"]},"required":true,"name":"X-Orka-Event-Type","in":"header"},{"schema":{"type":"string","description":"Unix time in seconds, when the request was signed."},"required":true,"name":"X-Orka-Timestamp","in":"header"},{"schema":{"type":"string","description":"`t=<timestamp>,v1=<hex>`, where the hex is `HMAC_SHA256(secret, timestamp + \".\" + raw_body)`."},"required":true,"name":"X-Orka-Signature","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the event. Deduplicate on it.","example":"evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6"},"type":{"type":"string","enum":["webhook.ping"]},"created_at":{"type":"string","format":"date-time","example":"2026-09-21T14:03:12.000Z"},"project_id":{"type":"string","example":"66b1f0a9e4b0a1b2c3d4e5f6"},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["id","type","created_at","project_id","data"]}}}},"responses":{"200":{"description":"Answer with any 2xx within 10 seconds."}}}}}}