> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/conversations.md).

# Conversations

The inbox. There is one conversation per contact per workroom, covering the full SMS, email, and voice thread. Conversations are addressed by the **contact ID** (`con_...`). Reply with `POST /conversations/{contact_id}/reply` (`channel` = `sms` or `email`).

## List contact conversations. Filter by open/closed, assigned staff, or tag.

> This list includes every conversation regardless of channel, including Instagram, Facebook Messenger, WhatsApp, and Gleanchat (web chat) - but \`listConversationMessages\` and \`replyToConversation\` only support sms, email, and voice (see their own descriptions). A conversation from one of those unsupported channels still appears here; its messages cannot be read or replied to via this API today.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"ResponsibleId":{"description":"A staff user id (`usr_<hex>`) or the literal string `AI` for AI-assisted conversations.","oneOf":[{"$ref":"#/components/schemas/StaffId"},{"type":"string","enum":["AI"]}]},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Conversation":{"type":"object","description":"Contact-scoped conversation state. One conversation per contact per workroom. The `id` on the wire is the contact's prefixed id (`con_<hex>`). Persistent state lives in `userdetails.conversations`.\n","properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","enum":["conversation"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","nullable":true},"contact_email":{"type":"string","nullable":true},"contact_phone":{"type":"string","nullable":true},"closed":{"type":"boolean"},"conversation_id":{"type":"string","nullable":true,"description":"Id of the current conversation record (the dashboard's userconversations row). Null right after a reopen. The next assign or tag change fills it in when it creates a new record; exactly like the dashboard inbox (v1 saveOpenConversationRecord), when an open record for the contact already exists it is updated in place and this stays null. A close always records the finished record's id in `closed_conversation_ids`. Do not treat it as a per-reopen counter."},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"}},"tags":{"type":"array","items":{"type":"string"},"description":"Titles of the inbox conversation tags on this conversation. Stored as conversation_tags ids, exactly as the dashboard inbox stores them; a stored value with no matching tag (a deleted tag) is returned as stored."},"tag_ids":{"type":"array","items":{"type":"string"},"description":"The conversation_tags ids behind `tags` (24-hex, unprefixed), for values that resolve to a tag."},"started_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Start of the CURRENT conversation instance, not necessarily the first-ever contact with this person - it resets to the reopen time whenever the conversation reopens (same instant as `reopened_at` on that event), matching `conversation_id` being cleared on reopen. History of prior instances is in `closed_conversation_ids`. Null on a small number of legacy conversations that predate this field being tracked."},"closed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Null whenever `closed` is false - a reopen clears this, it never carries over the previous close's date once the conversation is open again."},"closed_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null whenever `closed` is false, for the same reason as `closed_at`."},"reopened_at":{"$ref":"#/components/schemas/Timestamp","description":"Equals `started_at` at the moment of reopening - both are set to the same timestamp, since a reopen starts a new conversation instance. This is expected, not a data error."},"reopened_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null when the dashboard auto-reopened the conversation on inbound/outbound activity rather than a staff member reopening it - see `reopened_reason`."},"reopened_reason":{"type":"string","nullable":true,"description":"Set only on an auto-reopen (`reopened_by` is null): a free-form event label from the dashboard, e.g. `\"Email Received\"`. Null when `reopened_by` is set, and null when the conversation was never reopened."},"closed_conversation_ids":{"type":"array","items":{"type":"string"}},"messages_url":{"type":"string","nullable":true,"description":"Relative URL to fetch the message union. Convenience field."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/conversations":{"get":{"tags":["Conversations"],"operationId":"listConversations","summary":"List contact conversations. Filter by open/closed, assigned staff, or tag.","description":"This list includes every conversation regardless of channel, including Instagram, Facebook Messenger, WhatsApp, and Gleanchat (web chat) - but `listConversationMessages` and `replyToConversation` only support sms, email, and voice (see their own descriptions). A conversation from one of those unsupported channels still appears here; its messages cannot be read or replied to via this API today.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"closed":{"type":"boolean","description":"true → only closed; false → only open."},"responsible_id":{"$ref":"#/components/schemas/ResponsibleId"},"tag":{"type":"string"}}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}}}]}}}}}}}}}
```

## Retrieve one contact's conversation.

> The conversation state for a contact in this workroom: open or closed, assigned staff, and tags. There is one conversation per contact per workroom, so the ID here is the contact's ID. Messages are \`listConversationMessages\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"Conversation":{"type":"object","description":"Contact-scoped conversation state. One conversation per contact per workroom. The `id` on the wire is the contact's prefixed id (`con_<hex>`). Persistent state lives in `userdetails.conversations`.\n","properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","enum":["conversation"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","nullable":true},"contact_email":{"type":"string","nullable":true},"contact_phone":{"type":"string","nullable":true},"closed":{"type":"boolean"},"conversation_id":{"type":"string","nullable":true,"description":"Id of the current conversation record (the dashboard's userconversations row). Null right after a reopen. The next assign or tag change fills it in when it creates a new record; exactly like the dashboard inbox (v1 saveOpenConversationRecord), when an open record for the contact already exists it is updated in place and this stays null. A close always records the finished record's id in `closed_conversation_ids`. Do not treat it as a per-reopen counter."},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"}},"tags":{"type":"array","items":{"type":"string"},"description":"Titles of the inbox conversation tags on this conversation. Stored as conversation_tags ids, exactly as the dashboard inbox stores them; a stored value with no matching tag (a deleted tag) is returned as stored."},"tag_ids":{"type":"array","items":{"type":"string"},"description":"The conversation_tags ids behind `tags` (24-hex, unprefixed), for values that resolve to a tag."},"started_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Start of the CURRENT conversation instance, not necessarily the first-ever contact with this person - it resets to the reopen time whenever the conversation reopens (same instant as `reopened_at` on that event), matching `conversation_id` being cleared on reopen. History of prior instances is in `closed_conversation_ids`. Null on a small number of legacy conversations that predate this field being tracked."},"closed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Null whenever `closed` is false - a reopen clears this, it never carries over the previous close's date once the conversation is open again."},"closed_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null whenever `closed` is false, for the same reason as `closed_at`."},"reopened_at":{"$ref":"#/components/schemas/Timestamp","description":"Equals `started_at` at the moment of reopening - both are set to the same timestamp, since a reopen starts a new conversation instance. This is expected, not a data error."},"reopened_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null when the dashboard auto-reopened the conversation on inbound/outbound activity rather than a staff member reopening it - see `reopened_reason`."},"reopened_reason":{"type":"string","nullable":true,"description":"Set only on an auto-reopen (`reopened_by` is null): a free-form event label from the dashboard, e.g. `\"Email Received\"`. Null when `reopened_by` is set, and null when the conversation was never reopened."},"closed_conversation_ids":{"type":"array","items":{"type":"string"}},"messages_url":{"type":"string","nullable":true,"description":"Relative URL to fetch the message union. Convenience field."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"ResponsibleId":{"description":"A staff user id (`usr_<hex>`) or the literal string `AI` for AI-assisted conversations.","oneOf":[{"$ref":"#/components/schemas/StaffId"},{"type":"string","enum":["AI"]}]},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/conversations/{contact_id}":{"get":{"tags":["Conversations"],"operationId":"retrieveConversation","summary":"Retrieve one contact's conversation.","description":"The conversation state for a contact in this workroom: open or closed, assigned staff, and tags. There is one conversation per contact per workroom, so the ID here is the contact's ID. Messages are `listConversationMessages`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Return the merged message thread for a contact.

> Unions rows from 5 legacy collections (inboundtext, inboundemails, pushmessagessms, pushmessagesemail, phonecalls) filtered to this contact. Sorted most-recent first. This endpoint does NOT paginate via cursor — messages come from 5 sources; the union is bounded by \`limit\`. If you need more than 200, page by narrowing \`filter\[channel]\` or \`filter\[direction]\`.\
> \
> \*\*Instagram, Facebook Messenger, WhatsApp, and Gleanchat (web chat) are not supported.\*\* A conversation on one of those channels can appear in \`listConversations\`, but this endpoint has no source collection for them - it returns an empty or incomplete thread rather than an error. Only sms, email, and voice are covered.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"ConversationMessage":{"type":"object","description":"Unified message shape returned by `GET /conversations/{contact_id}/messages`. Sourced from 5 legacy collections (inboundtext, inboundemails, pushmessagessms, pushmessagesemail, phonecalls) and normalized on the wire. Not the same as the top-level `Message` schema returned by `/messages` — this one is the read-only union view.\n","properties":{"id":{"$ref":"#/components/schemas/MessageId","nullable":true},"object":{"type":"string","enum":["message"]},"channel":{"type":"string","enum":["sms","email","voice"]},"direction":{"type":"string","enum":["inbound","outbound"]},"body":{"type":"string","nullable":true,"description":"For voice, may contain `call_notes` if any."},"subject":{"type":"string","nullable":true,"description":"Email only."},"from":{"type":"string","nullable":true},"to":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"description":"Outbound: provider status (queued/sent/delivered/failed). Inbound: `received`."},"sent_at":{"$ref":"#/components/schemas/Timestamp"},"received_at":{"$ref":"#/components/schemas/Timestamp"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Sort key. Whichever of sent_at/received_at applies."},"media_urls":{"type":"array","items":{"type":"string","format":"uri"}},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Set if this message was sent by a campaign or flow (not a reply)."},"source":{"type":"string","description":"The underlying collection this row came from — for debugging / provenance."},"provider":{"type":"string","nullable":true,"enum":["twilio","telnyx","edgility","ringcentral",null],"description":"For outbound: which provider actually delivered this send. Populated on reply endpoints; may be null on older rows."},"provider_id":{"type":"string","nullable":true,"description":"Provider-side message id (Twilio SID, Telnyx message id, Edgility campaign_id). `dry_run_<hash>` when dry_run was set."}}},"MessageId":{"type":"string","pattern":"^msg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"}}},"paths":{"/conversations/{contact_id}/messages":{"get":{"tags":["Conversations"],"operationId":"listConversationMessages","summary":"Return the merged message thread for a contact.","description":"Unions rows from 5 legacy collections (inboundtext, inboundemails, pushmessagessms, pushmessagesemail, phonecalls) filtered to this contact. Sorted most-recent first. This endpoint does NOT paginate via cursor — messages come from 5 sources; the union is bounded by `limit`. If you need more than 200, page by narrowing `filter[channel]` or `filter[direction]`.\n\n**Instagram, Facebook Messenger, WhatsApp, and Gleanchat (web chat) are not supported.** A conversation on one of those channels can appear in `listConversations`, but this endpoint has no source collection for them - it returns an empty or incomplete thread rather than an error. Only sms, email, and voice are covered.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/LimitParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["sms","email","voice"]},"direction":{"type":"string","enum":["inbound","outbound"]}}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"}}}}]}}}}}}}}}
```

## Send an SMS or email as a reply from an operator.

> Sends through the workroom's provider (Twilio, Telnyx or Edgility for SMS; SMTP/Mailgun/SendGrid for email) and records the send in the inbox the same way the dashboard does: the message row, the contact's inbox preview and sort time, and SMS credit usage. If the conversation is closed, it auto-reopens. If the workroom lacks provider credentials (SMS) or a default from\_email (email), returns 422 with actionable detail. RingCentral is not supported. On accounts that bill SMS against prepaid credits, an SMS reply is refused with 422 \`insufficient\_sms\_credits\` when the balance is zero.\
> \
> Gates, as the dashboard inbox: 422 \`compliance\_block\` for an SMS reply to a contact who opted out of SMS, or — when the workroom's opt-in settings allow sending only to opted-in (or double-opted-in) contacts — to one who has not opted in (or not replied with an opt-in keyword); and for an email reply to a contact who unsubscribed from email. The SMS goes to the stored phone with a leading 0 dropped and the account's country code added.\
> \
> Side effects beyond the message row, as the dashboard: the conversation is assigned to the sending staff member (added to \`responsible\_ids\`) unless the workroom turned inbox auto-assign off; the reply's \`response\_time\` (seconds since the contact's latest inbound message, first reply only) is recorded for inbox response-time reports; and the mobile app's silent-push row is queued. The dashboard's MINDBODY contact-log push is not made.\
> \
> \*\*Only \`channel: "sms"\` or \`channel: "email"\` are accepted.\*\* Instagram, Facebook Messenger, WhatsApp, and Gleanchat (web chat) conversations cannot be replied to through this endpoint, even though they appear in \`listConversations\` - there is no social/chat send path wired into v3 today.\
> \
> \*\*Sends to a real person the moment it is called.\*\* There is no recall. This is a single reply to the one contact on this conversation - not a segment or campaign audience.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"ConversationReply":{"type":"object","required":["channel","body"],"properties":{"channel":{"type":"string","enum":["sms","email"]},"body":{"type":"string","description":"Message body. Plain text for SMS; HTML permitted for email. SMS: At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long`."},"subject":{"type":"string","description":"Email only. Defaults to \"Message from Gleantap\"."},"from_number":{"type":"string","description":"SMS only. Overrides the workroom default. Must match a number provisioned on THIS workroom under Twilio (appdetails.from[]), Telnyx (appdetails.telnyx.from or phone_numbers with type=telnyx), Edgility (appdetails.edgility.from), or RingCentral (ringcentralaccounts). Unknown numbers → 422 `validation_failed`.\n"},"from_email":{"type":"string","description":"Email only. The sender address (one of the workroom's sender emails); its configured name and Reply-To apply. Default: the workroom from_email, else the primary account user, else default_email — as the dashboard inbox."},"from_name":{"type":"string","description":"Email only. Overrides the resolved sender name (sender email's name, else the workroom from_sender_name, else the workroom name)."},"dry_run":{"type":"boolean","default":false,"description":"SMS only. When true, resolves the provider + from-number but does NOT actually hit Twilio/Telnyx/Edgility/RingCentral. Logs a message row with `dry_run=1` for auditability, but charges no SMS credits and leaves the conversation and inbox preview untouched.\n"}}},"ConversationMessage":{"type":"object","description":"Unified message shape returned by `GET /conversations/{contact_id}/messages`. Sourced from 5 legacy collections (inboundtext, inboundemails, pushmessagessms, pushmessagesemail, phonecalls) and normalized on the wire. Not the same as the top-level `Message` schema returned by `/messages` — this one is the read-only union view.\n","properties":{"id":{"$ref":"#/components/schemas/MessageId","nullable":true},"object":{"type":"string","enum":["message"]},"channel":{"type":"string","enum":["sms","email","voice"]},"direction":{"type":"string","enum":["inbound","outbound"]},"body":{"type":"string","nullable":true,"description":"For voice, may contain `call_notes` if any."},"subject":{"type":"string","nullable":true,"description":"Email only."},"from":{"type":"string","nullable":true},"to":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"description":"Outbound: provider status (queued/sent/delivered/failed). Inbound: `received`."},"sent_at":{"$ref":"#/components/schemas/Timestamp"},"received_at":{"$ref":"#/components/schemas/Timestamp"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Sort key. Whichever of sent_at/received_at applies."},"media_urls":{"type":"array","items":{"type":"string","format":"uri"}},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Set if this message was sent by a campaign or flow (not a reply)."},"source":{"type":"string","description":"The underlying collection this row came from — for debugging / provenance."},"provider":{"type":"string","nullable":true,"enum":["twilio","telnyx","edgility","ringcentral",null],"description":"For outbound: which provider actually delivered this send. Populated on reply endpoints; may be null on older rows."},"provider_id":{"type":"string","nullable":true,"description":"Provider-side message id (Twilio SID, Telnyx message id, Edgility campaign_id). `dry_run_<hash>` when dry_run was set."}}},"MessageId":{"type":"string","pattern":"^msg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/conversations/{contact_id}/reply":{"post":{"tags":["Conversations"],"operationId":"replyToConversation","summary":"Send an SMS or email as a reply from an operator.","description":"Sends through the workroom's provider (Twilio, Telnyx or Edgility for SMS; SMTP/Mailgun/SendGrid for email) and records the send in the inbox the same way the dashboard does: the message row, the contact's inbox preview and sort time, and SMS credit usage. If the conversation is closed, it auto-reopens. If the workroom lacks provider credentials (SMS) or a default from_email (email), returns 422 with actionable detail. RingCentral is not supported. On accounts that bill SMS against prepaid credits, an SMS reply is refused with 422 `insufficient_sms_credits` when the balance is zero.\n\nGates, as the dashboard inbox: 422 `compliance_block` for an SMS reply to a contact who opted out of SMS, or — when the workroom's opt-in settings allow sending only to opted-in (or double-opted-in) contacts — to one who has not opted in (or not replied with an opt-in keyword); and for an email reply to a contact who unsubscribed from email. The SMS goes to the stored phone with a leading 0 dropped and the account's country code added.\n\nSide effects beyond the message row, as the dashboard: the conversation is assigned to the sending staff member (added to `responsible_ids`) unless the workroom turned inbox auto-assign off; the reply's `response_time` (seconds since the contact's latest inbound message, first reply only) is recorded for inbox response-time reports; and the mobile app's silent-push row is queued. The dashboard's MINDBODY contact-log push is not made.\n\n**Only `channel: \"sms\"` or `channel: \"email\"` are accepted.** Instagram, Facebook Messenger, WhatsApp, and Gleanchat (web chat) conversations cannot be replied to through this endpoint, even though they appear in `listConversations` - there is no social/chat send path wired into v3 today.\n\n**Sends to a real person the moment it is called.** There is no recall. This is a single reply to the one contact on this conversation - not a segment or campaign audience.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationReply"}}}},"responses":{"201":{"description":"Sent + logged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessage"}}}},"422":{"description":"Validation or provider-configuration error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Provider (Twilio/SendGrid/Mailgun) rejected the send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```

## POST /conversations/{contact\_id}/assign

> Add one or more responsible staff to a conversation. Pass \`AI\` to enable AI handling.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"ConversationAssign":{"type":"object","required":["responsible_ids"],"properties":{"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"},"description":"Array of `usr_<hex>` ids, and/or the literal string `AI`."}}},"ResponsibleId":{"description":"A staff user id (`usr_<hex>`) or the literal string `AI` for AI-assisted conversations.","oneOf":[{"$ref":"#/components/schemas/StaffId"},{"type":"string","enum":["AI"]}]},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Conversation":{"type":"object","description":"Contact-scoped conversation state. One conversation per contact per workroom. The `id` on the wire is the contact's prefixed id (`con_<hex>`). Persistent state lives in `userdetails.conversations`.\n","properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","enum":["conversation"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","nullable":true},"contact_email":{"type":"string","nullable":true},"contact_phone":{"type":"string","nullable":true},"closed":{"type":"boolean"},"conversation_id":{"type":"string","nullable":true,"description":"Id of the current conversation record (the dashboard's userconversations row). Null right after a reopen. The next assign or tag change fills it in when it creates a new record; exactly like the dashboard inbox (v1 saveOpenConversationRecord), when an open record for the contact already exists it is updated in place and this stays null. A close always records the finished record's id in `closed_conversation_ids`. Do not treat it as a per-reopen counter."},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"}},"tags":{"type":"array","items":{"type":"string"},"description":"Titles of the inbox conversation tags on this conversation. Stored as conversation_tags ids, exactly as the dashboard inbox stores them; a stored value with no matching tag (a deleted tag) is returned as stored."},"tag_ids":{"type":"array","items":{"type":"string"},"description":"The conversation_tags ids behind `tags` (24-hex, unprefixed), for values that resolve to a tag."},"started_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Start of the CURRENT conversation instance, not necessarily the first-ever contact with this person - it resets to the reopen time whenever the conversation reopens (same instant as `reopened_at` on that event), matching `conversation_id` being cleared on reopen. History of prior instances is in `closed_conversation_ids`. Null on a small number of legacy conversations that predate this field being tracked."},"closed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Null whenever `closed` is false - a reopen clears this, it never carries over the previous close's date once the conversation is open again."},"closed_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null whenever `closed` is false, for the same reason as `closed_at`."},"reopened_at":{"$ref":"#/components/schemas/Timestamp","description":"Equals `started_at` at the moment of reopening - both are set to the same timestamp, since a reopen starts a new conversation instance. This is expected, not a data error."},"reopened_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null when the dashboard auto-reopened the conversation on inbound/outbound activity rather than a staff member reopening it - see `reopened_reason`."},"reopened_reason":{"type":"string","nullable":true,"description":"Set only on an auto-reopen (`reopened_by` is null): a free-form event label from the dashboard, e.g. `\"Email Received\"`. Null when `reopened_by` is set, and null when the conversation was never reopened."},"closed_conversation_ids":{"type":"array","items":{"type":"string"}},"messages_url":{"type":"string","nullable":true,"description":"Relative URL to fetch the message union. Convenience field."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/conversations/{contact_id}/assign":{"post":{"tags":["Conversations"],"operationId":"assignConversation","summary":"Add one or more responsible staff to a conversation. Pass `AI` to enable AI handling.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationAssign"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}}}}}}}
```

## POST /conversations/{contact\_id}/unassign

> Remove one or more responsible staff from a conversation. Removing the last one returns it to the inbox's Unassigned view.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"ConversationAssign":{"type":"object","required":["responsible_ids"],"properties":{"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"},"description":"Array of `usr_<hex>` ids, and/or the literal string `AI`."}}},"ResponsibleId":{"description":"A staff user id (`usr_<hex>`) or the literal string `AI` for AI-assisted conversations.","oneOf":[{"$ref":"#/components/schemas/StaffId"},{"type":"string","enum":["AI"]}]},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Conversation":{"type":"object","description":"Contact-scoped conversation state. One conversation per contact per workroom. The `id` on the wire is the contact's prefixed id (`con_<hex>`). Persistent state lives in `userdetails.conversations`.\n","properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","enum":["conversation"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","nullable":true},"contact_email":{"type":"string","nullable":true},"contact_phone":{"type":"string","nullable":true},"closed":{"type":"boolean"},"conversation_id":{"type":"string","nullable":true,"description":"Id of the current conversation record (the dashboard's userconversations row). Null right after a reopen. The next assign or tag change fills it in when it creates a new record; exactly like the dashboard inbox (v1 saveOpenConversationRecord), when an open record for the contact already exists it is updated in place and this stays null. A close always records the finished record's id in `closed_conversation_ids`. Do not treat it as a per-reopen counter."},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"}},"tags":{"type":"array","items":{"type":"string"},"description":"Titles of the inbox conversation tags on this conversation. Stored as conversation_tags ids, exactly as the dashboard inbox stores them; a stored value with no matching tag (a deleted tag) is returned as stored."},"tag_ids":{"type":"array","items":{"type":"string"},"description":"The conversation_tags ids behind `tags` (24-hex, unprefixed), for values that resolve to a tag."},"started_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Start of the CURRENT conversation instance, not necessarily the first-ever contact with this person - it resets to the reopen time whenever the conversation reopens (same instant as `reopened_at` on that event), matching `conversation_id` being cleared on reopen. History of prior instances is in `closed_conversation_ids`. Null on a small number of legacy conversations that predate this field being tracked."},"closed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Null whenever `closed` is false - a reopen clears this, it never carries over the previous close's date once the conversation is open again."},"closed_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null whenever `closed` is false, for the same reason as `closed_at`."},"reopened_at":{"$ref":"#/components/schemas/Timestamp","description":"Equals `started_at` at the moment of reopening - both are set to the same timestamp, since a reopen starts a new conversation instance. This is expected, not a data error."},"reopened_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null when the dashboard auto-reopened the conversation on inbound/outbound activity rather than a staff member reopening it - see `reopened_reason`."},"reopened_reason":{"type":"string","nullable":true,"description":"Set only on an auto-reopen (`reopened_by` is null): a free-form event label from the dashboard, e.g. `\"Email Received\"`. Null when `reopened_by` is set, and null when the conversation was never reopened."},"closed_conversation_ids":{"type":"array","items":{"type":"string"}},"messages_url":{"type":"string","nullable":true,"description":"Relative URL to fetch the message union. Convenience field."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/conversations/{contact_id}/unassign":{"post":{"tags":["Conversations"],"operationId":"unassignConversation","summary":"Remove one or more responsible staff from a conversation. Removing the last one returns it to the inbox's Unassigned view.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationAssign"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}}}}}}}
```

## POST /conversations/{contact\_id}/close

> Mark a conversation closed. Body can pass \`closed\_by\` (staff id).

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Conversation":{"type":"object","description":"Contact-scoped conversation state. One conversation per contact per workroom. The `id` on the wire is the contact's prefixed id (`con_<hex>`). Persistent state lives in `userdetails.conversations`.\n","properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","enum":["conversation"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","nullable":true},"contact_email":{"type":"string","nullable":true},"contact_phone":{"type":"string","nullable":true},"closed":{"type":"boolean"},"conversation_id":{"type":"string","nullable":true,"description":"Id of the current conversation record (the dashboard's userconversations row). Null right after a reopen. The next assign or tag change fills it in when it creates a new record; exactly like the dashboard inbox (v1 saveOpenConversationRecord), when an open record for the contact already exists it is updated in place and this stays null. A close always records the finished record's id in `closed_conversation_ids`. Do not treat it as a per-reopen counter."},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"}},"tags":{"type":"array","items":{"type":"string"},"description":"Titles of the inbox conversation tags on this conversation. Stored as conversation_tags ids, exactly as the dashboard inbox stores them; a stored value with no matching tag (a deleted tag) is returned as stored."},"tag_ids":{"type":"array","items":{"type":"string"},"description":"The conversation_tags ids behind `tags` (24-hex, unprefixed), for values that resolve to a tag."},"started_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Start of the CURRENT conversation instance, not necessarily the first-ever contact with this person - it resets to the reopen time whenever the conversation reopens (same instant as `reopened_at` on that event), matching `conversation_id` being cleared on reopen. History of prior instances is in `closed_conversation_ids`. Null on a small number of legacy conversations that predate this field being tracked."},"closed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Null whenever `closed` is false - a reopen clears this, it never carries over the previous close's date once the conversation is open again."},"closed_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null whenever `closed` is false, for the same reason as `closed_at`."},"reopened_at":{"$ref":"#/components/schemas/Timestamp","description":"Equals `started_at` at the moment of reopening - both are set to the same timestamp, since a reopen starts a new conversation instance. This is expected, not a data error."},"reopened_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null when the dashboard auto-reopened the conversation on inbound/outbound activity rather than a staff member reopening it - see `reopened_reason`."},"reopened_reason":{"type":"string","nullable":true,"description":"Set only on an auto-reopen (`reopened_by` is null): a free-form event label from the dashboard, e.g. `\"Email Received\"`. Null when `reopened_by` is set, and null when the conversation was never reopened."},"closed_conversation_ids":{"type":"array","items":{"type":"string"}},"messages_url":{"type":"string","nullable":true,"description":"Relative URL to fetch the message union. Convenience field."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"ResponsibleId":{"description":"A staff user id (`usr_<hex>`) or the literal string `AI` for AI-assisted conversations.","oneOf":[{"$ref":"#/components/schemas/StaffId"},{"type":"string","enum":["AI"]}]},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/conversations/{contact_id}/close":{"post":{"tags":["Conversations"],"operationId":"closeConversation","summary":"Mark a conversation closed. Body can pass `closed_by` (staff id).","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"closed_by":{"$ref":"#/components/schemas/StaffId"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}}}}}}}
```

## POST /conversations/{contact\_id}/reopen

> Reopen a closed conversation. Clears \`conversation\_id\` until the next assign, tag change, or close.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Conversation":{"type":"object","description":"Contact-scoped conversation state. One conversation per contact per workroom. The `id` on the wire is the contact's prefixed id (`con_<hex>`). Persistent state lives in `userdetails.conversations`.\n","properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","enum":["conversation"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","nullable":true},"contact_email":{"type":"string","nullable":true},"contact_phone":{"type":"string","nullable":true},"closed":{"type":"boolean"},"conversation_id":{"type":"string","nullable":true,"description":"Id of the current conversation record (the dashboard's userconversations row). Null right after a reopen. The next assign or tag change fills it in when it creates a new record; exactly like the dashboard inbox (v1 saveOpenConversationRecord), when an open record for the contact already exists it is updated in place and this stays null. A close always records the finished record's id in `closed_conversation_ids`. Do not treat it as a per-reopen counter."},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"}},"tags":{"type":"array","items":{"type":"string"},"description":"Titles of the inbox conversation tags on this conversation. Stored as conversation_tags ids, exactly as the dashboard inbox stores them; a stored value with no matching tag (a deleted tag) is returned as stored."},"tag_ids":{"type":"array","items":{"type":"string"},"description":"The conversation_tags ids behind `tags` (24-hex, unprefixed), for values that resolve to a tag."},"started_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Start of the CURRENT conversation instance, not necessarily the first-ever contact with this person - it resets to the reopen time whenever the conversation reopens (same instant as `reopened_at` on that event), matching `conversation_id` being cleared on reopen. History of prior instances is in `closed_conversation_ids`. Null on a small number of legacy conversations that predate this field being tracked."},"closed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Null whenever `closed` is false - a reopen clears this, it never carries over the previous close's date once the conversation is open again."},"closed_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null whenever `closed` is false, for the same reason as `closed_at`."},"reopened_at":{"$ref":"#/components/schemas/Timestamp","description":"Equals `started_at` at the moment of reopening - both are set to the same timestamp, since a reopen starts a new conversation instance. This is expected, not a data error."},"reopened_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null when the dashboard auto-reopened the conversation on inbound/outbound activity rather than a staff member reopening it - see `reopened_reason`."},"reopened_reason":{"type":"string","nullable":true,"description":"Set only on an auto-reopen (`reopened_by` is null): a free-form event label from the dashboard, e.g. `\"Email Received\"`. Null when `reopened_by` is set, and null when the conversation was never reopened."},"closed_conversation_ids":{"type":"array","items":{"type":"string"}},"messages_url":{"type":"string","nullable":true,"description":"Relative URL to fetch the message union. Convenience field."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"ResponsibleId":{"description":"A staff user id (`usr_<hex>`) or the literal string `AI` for AI-assisted conversations.","oneOf":[{"$ref":"#/components/schemas/StaffId"},{"type":"string","enum":["AI"]}]},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/conversations/{contact_id}/reopen":{"post":{"tags":["Conversations"],"operationId":"reopenConversation","summary":"Reopen a closed conversation. Clears `conversation_id` until the next assign, tag change, or close.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reopened_by":{"$ref":"#/components/schemas/StaffId"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}}}}}}}
```

## PUT /conversations/{contact\_id}/tags

> Replace the conversation's tag list (full-replace, not merge).

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversations","description":"The inbox surface — one conversation per contact per workroom, with union access to the full message thread across SMS, email, and voice channels. Persistent state (open/closed, responsible staff, tags) lives on `userdetails.conversations`. The route id is the contact id (`con_<hex>`), not a separate conversation id. Reply via `POST /conversations/{contact_id}/reply` (channel=sms|email). Uses the dashboard's existing send path (Twilio SMS + Mailgun/SMTP email). Note: legacy Gleantap does not track per-message `is_read` — the returned model matches what's actually stored.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"ConversationTagsUpdate":{"type":"object","required":["tags"],"properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Inbox conversation tags by title (case-insensitive) or conversation_tags id. Each must already exist in the contact's workroom (create it in the inbox) — an unknown one is rejected with 422 `unknown_tag`. Stored as ids, as the dashboard inbox does."}}},"Conversation":{"type":"object","description":"Contact-scoped conversation state. One conversation per contact per workroom. The `id` on the wire is the contact's prefixed id (`con_<hex>`). Persistent state lives in `userdetails.conversations`.\n","properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","enum":["conversation"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","nullable":true},"contact_email":{"type":"string","nullable":true},"contact_phone":{"type":"string","nullable":true},"closed":{"type":"boolean"},"conversation_id":{"type":"string","nullable":true,"description":"Id of the current conversation record (the dashboard's userconversations row). Null right after a reopen. The next assign or tag change fills it in when it creates a new record; exactly like the dashboard inbox (v1 saveOpenConversationRecord), when an open record for the contact already exists it is updated in place and this stays null. A close always records the finished record's id in `closed_conversation_ids`. Do not treat it as a per-reopen counter."},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/ResponsibleId"}},"tags":{"type":"array","items":{"type":"string"},"description":"Titles of the inbox conversation tags on this conversation. Stored as conversation_tags ids, exactly as the dashboard inbox stores them; a stored value with no matching tag (a deleted tag) is returned as stored."},"tag_ids":{"type":"array","items":{"type":"string"},"description":"The conversation_tags ids behind `tags` (24-hex, unprefixed), for values that resolve to a tag."},"started_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Start of the CURRENT conversation instance, not necessarily the first-ever contact with this person - it resets to the reopen time whenever the conversation reopens (same instant as `reopened_at` on that event), matching `conversation_id` being cleared on reopen. History of prior instances is in `closed_conversation_ids`. Null on a small number of legacy conversations that predate this field being tracked."},"closed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Null whenever `closed` is false - a reopen clears this, it never carries over the previous close's date once the conversation is open again."},"closed_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null whenever `closed` is false, for the same reason as `closed_at`."},"reopened_at":{"$ref":"#/components/schemas/Timestamp","description":"Equals `started_at` at the moment of reopening - both are set to the same timestamp, since a reopen starts a new conversation instance. This is expected, not a data error."},"reopened_by":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Null when the dashboard auto-reopened the conversation on inbound/outbound activity rather than a staff member reopening it - see `reopened_reason`."},"reopened_reason":{"type":"string","nullable":true,"description":"Set only on an auto-reopen (`reopened_by` is null): a free-form event label from the dashboard, e.g. `\"Email Received\"`. Null when `reopened_by` is set, and null when the conversation was never reopened."},"closed_conversation_ids":{"type":"array","items":{"type":"string"}},"messages_url":{"type":"string","nullable":true,"description":"Relative URL to fetch the message union. Convenience field."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"ResponsibleId":{"description":"A staff user id (`usr_<hex>`) or the literal string `AI` for AI-assisted conversations.","oneOf":[{"$ref":"#/components/schemas/StaffId"},{"type":"string","enum":["AI"]}]},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/conversations/{contact_id}/tags":{"put":{"tags":["Conversations"],"operationId":"replaceConversationTags","summary":"Replace the conversation's tag list (full-replace, not merge).","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationTagsUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"422":{"description":"A tag is not one of the workroom's inbox conversation tags (`unknown_tag`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```
