> ## Documentation Index > Fetch the complete documentation index at: https://docs.tied.com/llms.txt > Use this file to discover all available pages before exploring further. # Conversations List > List all the conversations with pagination ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/accounts/{account_id}/conversations openapi: 3.0.4 info: title: Tied API description: >- The Tied REST API. Three families of endpoint, each with its own credential: **Application** for everything inside an account, **Platform** for provisioning accounts and users, and **Client** for acting as a contact from your own surface. version: 1.1.0 termsOfService: https://tied.com/legal contact: email: hello@tied.com license: name: MIT License url: https://opensource.org/licenses/MIT servers: - url: https://app.tied.com description: Tied cloud security: [] tags: - name: Account AgentBots description: Account-specific Agent Bots - name: Agents description: Agent management APIs - name: Canned Responses description: Pre-defined responses for common queries - name: Contacts description: Contact management APIs - name: Contact Labels description: Manage contact labels - name: Conversation Assignments description: Manage conversation assignments - name: Conversation Labels description: Manage conversation labels - name: Conversations description: Conversation management APIs - name: Custom Attributes description: Custom fields for contacts and conversations - name: Custom Filters description: Saved filters for conversations - name: Inboxes description: Communication channels setup - name: Integrations description: Third-party integrations - name: Messages description: Message management APIs - name: Profile description: User profile APIs - name: Reports description: Analytics and reporting APIs - name: Teams description: Team management APIs - name: Webhooks description: Event notification webhooks - name: Automation Rule description: Workflow automation rules - name: Help Center description: Knowledge base management - name: Contacts API description: Public contact APIs - name: Conversations API description: Public conversation APIs - name: Messages API description: Public message APIs - name: CSAT Survey Page description: Customer satisfaction survey - name: Account description: >- The authenticated user's own account — read and update account settings. Distinct from the Platform family's **Accounts**, which provisions accounts across an installation. - name: Audit Logs description: Read the account's audit trail - name: Inbox API description: Public inbox lookup by channel identifier - name: Labels description: >- Create and manage the account's labels. Applying one to a conversation or contact is a separate endpoint under those resources. - name: Macros description: >- Saved multi-step actions an agent — or an integration — can run against one or more conversations. - name: Campaigns description: Ongoing website campaigns and one-off SMS and WhatsApp sends. - name: Contact Notes description: Internal notes on a contact. Never visible to the contact. - name: Help Center Categories description: Categories group a portal's articles, one tree per allowed locale. - name: Help Center Articles description: The articles a portal publishes, and their draft and archived states. - name: Summary Reports description: Per-agent, per-team, per-inbox and per-label totals for a period, as JSON. - name: Live Reports description: Right-now queue counts. No date range — these describe the present. - name: CSAT description: >- The satisfaction ratings contacts have submitted, and the metrics computed from them. - name: Notifications description: >- The per-user notification feed, its read and snooze state, and the settings that decide what lands in it. - name: Conversation Participants description: >- The agents watching a conversation. Participants get notified about it without being assigned to it. - name: Draft Messages description: >- The unsent reply held for a conversation. Stored in Redis, one per conversation. - name: Search description: >- One search service across conversations, contacts, messages and Help Center articles. - name: Dashboard Apps description: Embedded pages that appear as a tab beside a conversation. - name: Assignment Policies description: How conversations are handed out, and which inbox uses which policy. - name: Files description: Storing a file so another endpoint can attach it. - name: Bot Flows description: >- Scripted conversation flows, their versions, and the publish and rollback that move between them. - name: Billing description: >- Credit balance, usage, invoices, spend controls and the provider-hosted payment flows. - name: AMB Templates description: >- Saved Apple Messages primitive payloads an agent can reuse from the composer. - name: AMB Onboarding description: The in-flight Apple Messages for Business registration for an account. - name: Widget Session description: Starting a widget session and reading the visitor it belongs to. - name: Widget Conversation description: The visitor's conversation and its messages. - name: Widget Context description: Campaigns, agents, labels, events and uploads for a widget session. - name: CSAT Survey description: The public, unauthenticated survey a contact answers from a link. - name: Workspace description: Scheduling and cancelling deletion of the whole workspace. paths: /api/v1/accounts/{account_id}/conversations: parameters: - $ref: '#/components/parameters/account_id' get: tags: - Conversations summary: Conversations List description: List all the conversations with pagination operationId: conversationList parameters: - name: assignee_type in: query schema: type: string enum: - me - unassigned - all - assigned default: all description: Filter conversations by assignee type. - name: status in: query schema: type: string enum: - all - open - resolved - pending - snoozed default: open description: Filter by conversation status. - name: q in: query schema: type: string description: Filters conversations with messages containing the search term - name: inbox_id in: query schema: type: integer description: Restrict to one inbox. - name: team_id in: query schema: type: integer description: Restrict to one team. - name: labels in: query schema: type: array items: type: string description: >- Restrict to conversations carrying these label titles. Repeat as `labels[]=vip&labels[]=urgent`. - name: page in: query schema: type: integer default: 1 description: paginate through conversations responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/conversation_list' example: data: meta: mine_count: 1 assigned_count: 1 unassigned_count: 24 all_count: 25 payload: - meta: sender: additional_attributes: city: San Francisco country: United States location: San Francisco, United States description: >- Head of Customer Experience at Northwind Supply. Migrating off a legacy helpdesk and launching on Apple Messages first. Prefers async follow-up. company_name: Northwind Supply Co. country_code: US created_at_ip: 203.0.113.10 updated_at_ip: 203.0.113.10 avatar_url_hash: '0000000000000000000000000000000000000000' social_profiles: github: mokonkwo tiktok: northwindsupply twitter: mayabuildscx facebook: northwindsupply linkedin: maya-okonkwo instagram: northwind.supply last_avatar_sync_at: '2026-09-21T02:21:05Z' social_telegram_user_name: maya_okonkwo availability_status: offline email: maya@northwindsupply.com id: 135 name: Maya Okonkwo phone_number: '+14155550198' blocked: false identifier: in_example thumbnail: >- https://app.tied.com/rails/active_storage/blobs/proxy/EXAMPLE/avatar.png thumbnail_background_color: null domain_logo_avatar: false customer_verified: true custom_attributes: plan_tier: Premium lead_source: Apple Messages — pricing page profile_url: https://tied.com/customers/northwind-supply customer_since: '2024-03-15' lifetime_value: '48500' loyalty_discount: '12' newsletter_opt_in: true satisfaction_score: '92' last_activity_at: 1789957263 created_at: 1789957262 channel: Channel::Amb assignee: id: 1 account_id: 1 availability_status: offline auto_offline: true confirmed: true email: you@example.com provider: email available_name: Alex Rivera name: Alex Rivera role: administrator thumbnail: /dashboard/images/default-contact-avatars/031.svg avatar_url: '' illustration_avatar: true accent_color: null custom_role_id: null hmac_verified: false id: 155 messages: - id: 507 content: Tuesday at 11 works — see you then! account_id: 1 inbox_id: 1 conversation_id: 155 message_type: 0 created_at: 1789957083 updated_at: '2026-09-21T02:18:03.023Z' private: false status: sent source_id: null content_type: text content_attributes: {} sender_type: Contact sender_id: 135 external_source_ids: {} additional_attributes: {} processed_message_content: null sentiment: {} source_identity_uniqueness_exempt_at: null actor: null conversation: assignee_id: 1 unread_count: 0 last_activity_at: 1789957263 contact_inbox: source_id: sr_example sender: additional_attributes: city: San Francisco country: United States location: San Francisco, United States description: >- Head of Customer Experience at Northwind Supply. Migrating off a legacy helpdesk and launching on Apple Messages first. Prefers async follow-up. company_name: Northwind Supply Co. country_code: US created_at_ip: 203.0.113.10 updated_at_ip: 203.0.113.10 avatar_url_hash: '0000000000000000000000000000000000000000' social_profiles: github: mokonkwo tiktok: northwindsupply twitter: mayabuildscx facebook: northwindsupply linkedin: maya-okonkwo instagram: northwind.supply last_avatar_sync_at: '2026-09-21T02:21:05Z' social_telegram_user_name: maya_okonkwo custom_attributes: plan_tier: Premium lead_source: Apple Messages — pricing page profile_url: https://tied.com/customers/northwind-supply customer_since: '2024-03-15' lifetime_value: '48500' loyalty_discount: '12' newsletter_opt_in: true satisfaction_score: '92' email: maya@northwindsupply.com id: 135 identifier: in_example name: Maya Okonkwo phone_number: '+14155550198' thumbnail: >- https://app.tied.com/rails/active_storage/blobs/proxy/EXAMPLE/avatar.png thumbnail_background_color: null domain_logo_avatar: false customer_verified: true blocked: false type: contact account_id: 1 uuid: 00000000-0000-4000-8000-000000000000 additional_attributes: browser: device_name: iPhone browser_name: Safari platform_name: iOS browser_version: '18.4' platform_version: '18.4' referer: https://tied.com/pricing initiated_at: timestamp: 2026-09-21 02:21:02 UTC browser_language: en spinoco_instance_id: demo-instance-8 agent_last_seen_at: 1789957143 assignee_last_seen_at: 0 can_reply: true contact_last_seen_at: 0 custom_attributes: setup_stage: Apple Messages connected — flows next migrating_from: Legacy helpdesk — 40k tickets to import primary_channel: Apple Messages onboarding_status: Confirmed onboarding_call_at: '2026-09-22T11:00:00Z' inbox_id: 1 labels: - needs-reply - scheduling muted: false snoozed_until: null status: open created_at: 1789957262 updated_at: 1789957265.1759071 timestamp: 1789957263 first_reply_created_at: 0 unread_count: 0 last_non_activity_message: id: 507 content: Tuesday at 11 works — see you then! account_id: 1 inbox_id: 1 conversation_id: 155 message_type: 0 created_at: 1789957083 updated_at: '2026-09-21T02:18:03.023Z' private: false status: sent source_id: null content_type: text content_attributes: {} sender_type: Contact sender_id: 135 external_source_ids: {} additional_attributes: {} processed_message_content: null sentiment: {} source_identity_uniqueness_exempt_at: null actor: null conversation: assignee_id: 1 unread_count: 0 last_activity_at: 1789957263 contact_inbox: source_id: sr_example sender: additional_attributes: city: San Francisco country: United States location: San Francisco, United States description: >- Head of Customer Experience at Northwind Supply. Migrating off a legacy helpdesk and launching on Apple Messages first. Prefers async follow-up. company_name: Northwind Supply Co. country_code: US created_at_ip: 203.0.113.10 updated_at_ip: 203.0.113.10 avatar_url_hash: '0000000000000000000000000000000000000000' social_profiles: github: mokonkwo tiktok: northwindsupply twitter: mayabuildscx facebook: northwindsupply linkedin: maya-okonkwo instagram: northwind.supply last_avatar_sync_at: '2026-09-21T02:21:05Z' social_telegram_user_name: maya_okonkwo custom_attributes: plan_tier: Premium lead_source: Apple Messages — pricing page profile_url: https://tied.com/customers/northwind-supply customer_since: '2024-03-15' lifetime_value: '48500' loyalty_discount: '12' newsletter_opt_in: true satisfaction_score: '92' email: maya@northwindsupply.com id: 135 identifier: in_example name: Maya Okonkwo phone_number: '+14155550198' thumbnail: >- https://app.tied.com/rails/active_storage/blobs/proxy/EXAMPLE/avatar.png thumbnail_background_color: null domain_logo_avatar: false customer_verified: true blocked: false type: contact last_activity_at: 1789957263 priority: high waiting_since: 0 sla_policy_id: null - meta: sender: additional_attributes: {} availability_status: offline email: null id: 15 name: Sophia Reed phone_number: null blocked: false identifier: null thumbnail: '' thumbnail_background_color: null domain_logo_avatar: false customer_verified: false custom_attributes: {} created_at: 1789850192 channel: Channel::Whatsapp hmac_verified: false id: 161 messages: - id: 543 content: Do we need an approved template for this? account_id: 1 inbox_id: 3 conversation_id: 161 message_type: 0 created_at: 1789953903 updated_at: '2026-09-21T01:25:03.118Z' private: false status: sent source_id: null content_type: text content_attributes: {} sender_type: Contact sender_id: 15 external_source_ids: {} additional_attributes: {} processed_message_content: null sentiment: {} source_identity_uniqueness_exempt_at: null actor: null conversation: assignee_id: null unread_count: 0 last_activity_at: 1789953663 contact_inbox: source_id: sr_example sender: additional_attributes: {} custom_attributes: {} email: null id: 15 identifier: null name: Sophia Reed phone_number: null thumbnail: '' thumbnail_background_color: null domain_logo_avatar: false customer_verified: false blocked: false type: contact account_id: 1 uuid: 00000000-0000-4000-8000-000000000000 additional_attributes: {} agent_last_seen_at: 1789953963 assignee_last_seen_at: 0 can_reply: true contact_last_seen_at: 0 custom_attributes: {} inbox_id: 3 labels: [] muted: false snoozed_until: null status: open created_at: 1789957263 updated_at: 1789957263.3044538 timestamp: 1789953663 first_reply_created_at: 0 unread_count: 0 last_non_activity_message: id: 543 content: Do we need an approved template for this? account_id: 1 inbox_id: 3 conversation_id: 161 message_type: 0 created_at: 1789953903 updated_at: '2026-09-21T01:25:03.118Z' private: false status: sent source_id: null content_type: text content_attributes: {} sender_type: Contact sender_id: 15 external_source_ids: {} additional_attributes: {} processed_message_content: null sentiment: {} source_identity_uniqueness_exempt_at: null actor: null conversation: assignee_id: null unread_count: 0 last_activity_at: 1789953663 contact_inbox: source_id: sr_example sender: additional_attributes: {} custom_attributes: {} email: null id: 15 identifier: null name: Sophia Reed phone_number: null thumbnail: '' thumbnail_background_color: null domain_logo_avatar: false customer_verified: false blocked: false type: contact last_activity_at: 1789953663 priority: null waiting_since: 0 sla_policy_id: null '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/error_message' security: - userApiKey: [] components: parameters: account_id: in: path name: id schema: type: integer required: true description: The numeric ID of the account schemas: conversation_list: type: object properties: data: type: object properties: meta: type: object properties: mine_count: type: number description: Conversations assigned to the calling user. unassigned_count: type: number description: Conversations with no assignee. assigned_count: type: number description: Conversations with an assignee. all_count: type: number description: Every conversation matching the filters. description: >- Counts across the whole account for the current filters, not just this page. payload: type: array description: array of conversations items: allOf: - $ref: '#/components/schemas/generic_id' - $ref: '#/components/schemas/conversation' - type: object properties: meta: type: object properties: sender: type: object properties: additional_attributes: type: object description: The additional attributes of the sender availability_status: type: string description: The availability status of the sender email: type: string description: The email of the sender nullable: true id: type: number description: ID fo the sender name: type: string description: The name of the sender phone_number: type: string description: The phone number of the sender nullable: true blocked: type: boolean description: Whether the sender is blocked identifier: type: string description: The identifier of the sender nullable: true thumbnail: type: string description: Avatar URL of the contact custom_attributes: type: object description: The custom attributes of the sender last_activity_at: type: number description: The last activity at of the sender created_at: type: number description: The created at of the sender channel: type: string description: Channel Type assignee: $ref: '#/components/schemas/user' hmac_verified: type: boolean description: Whether the hmac is verified description: >- The conversation list is nested under `data`, one level deeper than most list endpoints. error_message: type: object description: >- The shape returned by `render_unauthorized`, `render_not_found_error` and `render_could_not_create_error`. properties: error: type: string description: A single human-readable message. example: Resource could not be found required: - error generic_id: type: object properties: id: type: number description: The numeric ID of the record. conversation: type: object properties: id: type: number description: ID of the conversation messages: type: array items: $ref: '#/components/schemas/message' description: The messages in the thread, oldest first. account_id: type: number description: Account Id uuid: type: string description: UUID of the conversation additional_attributes: type: object description: >- The object containing additional attributes related to the conversation agent_last_seen_at: type: number description: The last activity at of the agent assignee_last_seen_at: type: number description: The last activity at of the assignee can_reply: type: boolean description: Whether the conversation can be replied to contact_last_seen_at: type: number description: The last activity at of the contact custom_attributes: type: object description: >- The object to save custom attributes for conversation, accepts custom attributes key and value inbox_id: type: number description: ID of the inbox labels: type: array items: type: string description: The labels of the conversation muted: type: boolean description: Whether the conversation is muted snoozed_until: type: number description: The time at which the conversation will be unmuted nullable: true status: type: string enum: - open - resolved - pending description: The status of the conversation created_at: type: number description: The time at which conversation was created updated_at: type: number description: The time at which conversation was updated timestamp: description: Unix epoch seconds for the conversation's last activity. type: integer format: int64 first_reply_created_at: type: number description: The time at which the first reply was created unread_count: type: number description: The number of unread messages last_non_activity_message: $ref: '#/components/schemas/message' last_activity_at: type: number description: The last activity at of the conversation priority: type: string description: The priority of the conversation nullable: true waiting_since: type: number description: The time at which the conversation was waiting sla_policy_id: type: number description: The ID of the SLA policy nullable: true applied_sla: type: object description: The applied SLA sla_events: type: array items: type: object description: SLA event objects description: SLA breaches and warnings recorded against this conversation. user: type: object properties: id: type: number description: The numeric ID of the user. access_token: type: string description: >- The user's `userApiKey`. Treat it as a credential — anything holding it can do whatever this user can. account_id: type: number description: The account the response is scoped to. available_name: type: string description: >- What contacts see: the display name when one is set, otherwise the full name. avatar_url: type: string description: URL of an uploaded avatar. Empty when the user has not uploaded one. confirmed: type: boolean description: Whether the user has confirmed their email address. display_name: type: string nullable: true description: >- The name shown to contacts instead of the full name. Null when unset. message_signature: type: string nullable: true description: >- Appended to outgoing replies on inboxes with signatures enabled. Null when unset. email: type: string description: The user's email address, which is also their login. hmac_identifier: type: string description: Identifier used when computing identity verification hashes. inviter_id: type: number nullable: true description: The user who invited this one. Null for the account creator. name: type: string description: The user's full name. provider: type: string description: How the user signs in — `email` for a password login. pubsub_token: type: string description: >- Token for the realtime channel this user subscribes to. Treat it as a credential. role: type: string enum: - agent - administrator description: The role in the account this response is scoped to. ui_settings: type: object description: Dashboard preferences — sidebar state, chosen avatar, and similar. uid: type: string description: >- The unique identifier the auth provider knows the user by. The same as the email for a password login. type: type: string nullable: true description: Set for non-human users such as agent bots. Null for a person. custom_attributes: type: object description: >- Available for users who are created through platform APIs and has custom attributes associated. accounts: type: array items: type: object properties: id: type: number description: The account ID. name: type: string description: The account name. status: type: string description: Whether the account is active or suspended. active_at: type: string format: date-time description: >- When the user last used this account. Drives which account the dashboard opens on. role: type: string enum: - administrator - agent description: The user's role in this account. permissions: type: array items: type: string description: >- The effective permissions, expanded from the role and any custom role. availability: type: string description: The availability the user has chosen in this account. availability_status: type: string description: >- The availability Tied computes, which automatic offline can pull to `offline` regardless of the choice. auto_offline: type: boolean description: >- Whether Tied drops this user offline automatically when they go idle. custom_role_id: type: number nullable: true description: The custom role applied in this account, if any. custom_role: type: object nullable: true description: >- The expanded custom role. Null when the user has only a standard role. description: >- Every account this user belongs to, with their role and availability in each. A user can be an administrator in one and an agent in another. thumbnail: type: string description: Path or URL of the avatar shown in the dashboard. illustration_avatar: type: boolean description: >- Whether `thumbnail` is a generated illustration rather than an upload. message: type: object properties: id: type: number description: The ID of the message content: type: string description: The text content of the message nullable: true account_id: type: number description: The ID of the account inbox_id: type: number description: The ID of the inbox conversation_id: type: number description: The ID of the conversation message_type: description: 0 = incoming, 1 = outgoing, 2 = activity, 3 = template. type: integer enum: - 0 - 1 - 2 - 3 created_at: type: integer description: The time at which message was created updated_at: description: >- ISO-8601 timestamp of the last update. Note this differs from `created_at` on the same object, which is unix epoch seconds. type: string format: date-time nullable: true private: type: boolean description: The flags which shows whether the message is private or not status: type: string enum: - sent - delivered - read - failed description: The status of the message source_id: type: string description: The source ID of the message nullable: true content_type: type: string enum: - text - input_select - cards - form description: The type of the template message content_attributes: type: object description: The content attributes for each content_type sender_type: description: >- The class of the sender, capitalised to match the underlying record type. type: string enum: - Contact - User - AgentBot nullable: true sender_id: type: number description: The ID of the sender external_source_ids: type: object description: The external source IDs of the message additional_attributes: type: object description: The additional attributes of the message processed_message_content: type: string description: The processed message content nullable: true sentiment: type: object description: The sentiment of the message conversation: type: object description: The conversation object attachment: type: object description: The file object attached to the image sender: type: object description: User/Agent/AgentBot object securitySchemes: userApiKey: type: apiKey in: header name: api_access_token description: >- This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.