> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt > Use this file to discover all available pages before exploring further. # List chats > **Protocols:** Linked Device API **Required scope:** `chats:read` Lists conversations with stored messages for a Number with hosted message storage, most recent activity first. Beta: requires team enrollment. ## OpenAPI ````yaml api-reference/features/communicate.json GET /messaging/{session}/chats openapi: 3.0.3 info: title: Communicate API methods version: 1.0.0 description: >- Task-focused communicate methods across supported Polymorfa connection types. servers: [] security: [] paths: /messaging/{session}/chats: get: tags: - Chats summary: List chats description: >- **Protocols:** Linked Device API **Required scope:** `chats:read` Lists conversations with stored messages for a Number with hosted message storage, most recent activity first. Beta: requires team enrollment. operationId: nativeListChats parameters: - schema: type: string minLength: 1 description: Number ID. required: true name: session in: path description: |- Identifier of the connected Polymorfa session. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | At least `1` characters | - schema: type: integer minimum: 1 maximum: 100 default: 50 description: Page size, from 1 through 100. example: 50 required: false name: limit in: query description: |- Specifies limit for this query parameter. **Value constraints** | Constraint | Accepted input | | --- | --- | | Numeric value | `1` through `100` (inclusive) | - schema: type: string minLength: 1 maxLength: 1024 pattern: ^[A-Za-z0-9_-]+$ description: >- Opaque cursor from `nextCursor` or `previousCursor`. Reuse it only with the same path and filters. required: false name: cursor in: query description: |- Specifies cursor for this query parameter. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `1024` characters | | Pattern | `^[A-Za-z0-9_-]+$` | - schema: type: string enum: - direct - group - channel - broadcast description: Return only conversations of this kind. required: false name: kind in: query description: |- Kind discriminator for this object. **Allowed values** | Value | Meaning | | --- | --- | | `direct` | Direct. | | `group` | Group. | | `channel` | Channel. | | `broadcast` | Broadcast. | - schema: type: string format: date-time description: >- Return conversations with activity at or after this time (ISO 8601). required: false name: activeSince in: query description: |- Specifies active since for this query parameter. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `date-time` | - schema: type: string format: date-time description: >- Return conversations whose latest activity is before this time (ISO 8601). required: false name: activeBefore in: query description: |- Specifies active before for this query parameter. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `date-time` | responses: '200': description: One page of conversations headers: Polymorfa-Data-Region: description: Data region that served the stored history. schema: type: string content: application/json: schema: $ref: '#/components/schemas/native__ListChatsResponse' '400': description: A filter or cursor is invalid. content: application/json: schema: $ref: '#/components/schemas/native__PublicError' '401': description: The credential is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/native__PublicError' '403': description: >- The credential lacks the scope, is a client token, or the team is not enrolled in the beta. content: application/json: schema: $ref: '#/components/schemas/native__PublicError' '404': description: >- The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`). content: application/json: schema: $ref: '#/components/schemas/native__PublicError' '503': description: The history service for the Number's data region is unavailable. content: application/json: schema: $ref: '#/components/schemas/native__PublicError' security: - native__BearerAuth: [] servers: - url: https://api.polymorfa.com components: schemas: native__ListChatsResponse: type: object properties: success: type: boolean enum: - true description: |- Whether the request succeeded. **Allowed values** | Value | Meaning | | --- | --- | | `true` | True. | data: type: array items: $ref: '#/components/schemas/native__HistoryChat' description: Structured data carried by this object. hasMore: type: boolean description: True when `nextCursor` returns more items. nextCursor: type: string nullable: true description: |- Specifies next cursor for this native list chats response. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | previousCursor: type: string nullable: true description: |- Always null for conversations. Use nextCursor to continue listing. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | required: - success - data - hasMore - nextCursor - previousCursor native__PublicError: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - conflict_error - rate_limit_error - api_error - upstream_error description: |- Type discriminator for this object. **Allowed values** | Value | Meaning | | --- | --- | | `invalid_request_error` | Invalid request error. | | `authentication_error` | Authentication error. | | `permission_error` | Permission error. | | `conflict_error` | Conflict error. | | `rate_limit_error` | Rate limit error. | | `api_error` | Api error. | | `upstream_error` | Upstream error. | code: type: string enum: - invalid_parameter - invalid_credential - entitlement_required - gate_limit_reached - method_not_allowed - permission_denied - missing_scope - resource_not_found - hms_not_enabled - media_fetch_failed - resource_gone - feature_unavailable - stream_cursor_invalid - stream_cursor_expired - stream_connection_limit_reached - state_conflict - idempotency_conflict - idempotency_in_progress - idempotency_completed - idempotency_outcome_unknown - call_claimed - call_not_ringing - connection_limit - unsupported_for_connection - call_permission_required - invalid_sip_trunk - calls_disabled - call_recipient_opted_out - call_destination_blocked - call_permission_request_limited - call_permission_granted - call_opt_out_limit - number_restricted - sip_trunk_in_use - sip_trunk_revision_conflict - sip_trunk_limit - sip_unavailable - voice_not_enabled - provider_credential_invalid - provider_unavailable - asset_not_ready - voice_asset_in_use - voice_asset_revision_conflict - voice_unavailable - rate_limit_exceeded - internal_error - operation_not_supported - upstream_failure - service_unavailable - credential_verification_unavailable - session_not_ready - command_dispatch_failed - result_unknown - recipient_not_on_whatsapp - conversation_window_closed - template_not_approved - media_too_large - whatsapp_rate_limited - new_chat_limit_reached - whatsapp_account_restricted - bansafe_suspended - bansafe_org_suspended - bansafe_cold_blocked - bansafe_cold_held - bansafe_throttled - bansafe_daily_allowance_reached - bansafe_accounting_unavailable - bansafe_send_outcome_unknown - campaigns_not_entitled - campaign_throughput_capped description: >- Stable machine-readable code for this result. **Allowed values** | Value | Meaning | | --- | --- | | `invalid_parameter` | Invalid parameter. | | `invalid_credential` | Invalid credential. | | `entitlement_required` | Entitlement required. | | `gate_limit_reached` | Gate limit reached. | | `method_not_allowed` | Method not allowed. | | `permission_denied` | Permission denied. | | `missing_scope` | Missing scope. | | `resource_not_found` | Resource not found. | | `hms_not_enabled` | Hms not enabled. | | `media_fetch_failed` | Media fetch failed. | | `resource_gone` | Resource gone. | | `feature_unavailable` | Feature unavailable. | | `stream_cursor_invalid` | Stream cursor invalid. | | `stream_cursor_expired` | Stream cursor expired. | | `stream_connection_limit_reached` | Stream connection limit reached. | | `state_conflict` | State conflict. | | `idempotency_conflict` | Idempotency conflict. | | `idempotency_in_progress` | Idempotency in progress. | | `idempotency_completed` | Idempotency completed. | | `idempotency_outcome_unknown` | Idempotency outcome unknown. | | `call_claimed` | Call claimed. | | `call_not_ringing` | Call not ringing. | | `connection_limit` | Connection limit. | | `unsupported_for_connection` | Unsupported for connection. | | `call_permission_required` | Call permission required. | | `invalid_sip_trunk` | Invalid sip trunk. | | `calls_disabled` | Calls disabled. | | `call_recipient_opted_out` | Call recipient opted out. | | `call_destination_blocked` | Call destination blocked. | | `call_permission_request_limited` | Call permission request limited. | | `call_permission_granted` | Call permission granted. | | `call_opt_out_limit` | Call opt out limit. | | `number_restricted` | Number restricted. | | `sip_trunk_in_use` | Sip trunk in use. | | `sip_trunk_revision_conflict` | Sip trunk revision conflict. | | `sip_trunk_limit` | Sip trunk limit. | | `sip_unavailable` | Sip unavailable. | | `voice_not_enabled` | Voice not enabled. | | `provider_credential_invalid` | Provider credential invalid. | | `provider_unavailable` | Provider unavailable. | | `asset_not_ready` | Asset not ready. | | `voice_asset_in_use` | Voice asset in use. | | `voice_asset_revision_conflict` | Voice asset revision conflict. | | `voice_unavailable` | Voice unavailable. | | `rate_limit_exceeded` | Rate limit exceeded. | | `internal_error` | Internal error. | | `operation_not_supported` | Operation not supported. | | `upstream_failure` | Upstream failure. | | `service_unavailable` | Service unavailable. | | `credential_verification_unavailable` | Credential verification unavailable. | | `session_not_ready` | Session not ready. | | `command_dispatch_failed` | Command dispatch failed. | | `result_unknown` | Result unknown. | | `recipient_not_on_whatsapp` | Recipient not on whatsapp. | | `conversation_window_closed` | Conversation window closed. | | `template_not_approved` | Template not approved. | | `media_too_large` | Media too large. | | `whatsapp_rate_limited` | Whatsapp rate limited. | | `new_chat_limit_reached` | New chat limit reached. | | `whatsapp_account_restricted` | Whatsapp account restricted. | | `bansafe_suspended` | Bansafe suspended. | | `bansafe_org_suspended` | Bansafe org suspended. | | `bansafe_cold_blocked` | Bansafe cold blocked. | | `bansafe_cold_held` | Bansafe cold held. | | `bansafe_throttled` | Bansafe throttled. | | `bansafe_daily_allowance_reached` | Bansafe daily allowance reached. | | `bansafe_accounting_unavailable` | Bansafe accounting unavailable. | | `bansafe_send_outcome_unknown` | Bansafe send outcome unknown. | | `campaigns_not_entitled` | Campaigns not entitled. | | `campaign_throughput_capped` | Campaign throughput capped. | message: type: string description: Human-readable message associated with this result. param: type: string nullable: true description: |- Specifies param for this error. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | request_id: type: string description: >- Matches the X-Request-Id response header. Include it when you contact support. request_log_url: type: string format: uri description: >- Console page that shows this request. Returned only to organization and project credentials whose request was logged. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uri` | required: - type - code - message - param - request_id description: Error details returned when the operation fails. data: type: string nullable: true enum: - null description: |- Always null for a failed request. **Allowed values** | Value | Meaning | | --- | --- | | `null` | Null. | **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | docs: type: string format: uri description: |- Specifies docs for this native public error. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uri` | required: - error - data - docs native__HistoryChat: type: object properties: conversation: allOf: - $ref: '#/components/schemas/native__ConversationIdentity' description: Public conversation identifier or E.164 phone number. kind: type: string enum: - direct - group - channel - broadcast description: |- Kind discriminator for this object. **Allowed values** | Value | Meaning | | --- | --- | | `direct` | Direct. | | `group` | Group. | | `channel` | Channel. | | `broadcast` | Broadcast. | lastActivityAt: type: string format: date-time description: |- Timestamp for last activity at. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `date-time` | lastMessage: allOf: - $ref: '#/components/schemas/native__HistoryMessageSummary' description: Specifies last message for this native history chat. required: - conversation - kind - lastActivityAt - lastMessage native__ConversationIdentity: type: object properties: id: type: string pattern: ^[1-9][0-9]{0,18}$ description: |- Opaque Polymorfa resource ID. Keep this value as a string. **Value constraints** | Constraint | Accepted input | | --- | --- | | Pattern | `^[1-9][0-9]{0,18}$` | example: '739182640518203' phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ description: |- Phone number in international format. **Value constraints** | Constraint | Accepted input | | --- | --- | | Pattern | `^\+[1-9]\d{1,14}$` | bsuid: type: string pattern: ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$ description: >- Business-scoped user identifier (BSUID), scoped to the owning business portfolio. **Value constraints** | Constraint | Accepted input | | --- | --- | | Pattern | `^[A-Z]{2}\.[A-Za-z0-9]{1,128}$` | username: type: string minLength: 1 maxLength: 256 description: |- WhatsApp username when one is available. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `256` characters | required: - id additionalProperties: false native__HistoryMessageSummary: type: object properties: id: type: string pattern: ^[1-9][0-9]{0,18}$ description: |- Opaque Polymorfa resource ID. Keep this value as a string. **Value constraints** | Constraint | Accepted input | | --- | --- | | Pattern | `^[1-9][0-9]{0,18}$` | example: '739182640518203' whatsapp_ids: allOf: - $ref: '#/components/schemas/native__WhatsAppMessageIds' description: >- Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `object`; Required fields: `linked_devices` | | Alternative 2 | Type: `object`; Required fields: `official_api` | whatsapp_id: type: string minLength: 1 maxLength: 512 description: >- Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `512` characters | deprecated: true direction: type: string enum: - inbound - outbound description: |- Specifies direction for this native history message summary. **Allowed values** | Value | Meaning | | --- | --- | | `inbound` | Inbound. | | `outbound` | Outbound. | type: type: string description: Type discriminator for this object. timestamp: type: string format: date-time description: |- ISO 8601 timestamp associated with this event. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `date-time` | required: - id - whatsapp_ids - direction - type - timestamp native__WhatsAppMessageIds: anyOf: - type: object properties: linked_devices: type: string minLength: 1 maxLength: 512 description: |- Specifies linked devices for this any of. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `512` characters | official_api: type: string minLength: 1 maxLength: 512 description: |- Specifies official api for this any of. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `512` characters | required: - linked_devices additionalProperties: false - type: object properties: linked_devices: type: string minLength: 1 maxLength: 512 description: |- Specifies linked devices for this any of. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `512` characters | official_api: type: string minLength: 1 maxLength: 512 description: |- Specifies official api for this any of. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `512` characters | required: - official_api additionalProperties: false description: >- Exact message references observed through Linked Devices, the Official API, or both. Use the Polymorfa message id for actions and replies. Unknown provider references are omitted. securitySchemes: native__BearerAuth: type: http scheme: bearer description: >- Polymorfa organization key (pmfa_ prefix), project token (pmfa_pt_ prefix) where supported, or short-lived client token (pmfa_ct_ prefix). Organization and project keys may be personal or service-account owned and enforce selected action scopes. Organization keys cover the team and its projects; project tokens stay inside one project. Client tokens stay inside their live project and session and enforce their client rules. ````