> ## Documentation Index > Fetch the complete documentation index at: https://docs.dialtu.com/llms.txt > Use this file to discover all available pages before exploring further. # List WhatsApp conversations > List WhatsApp conversations (sessions) with their inline transcripts. Results are a flat, paginated list of sessions ordered by `sort_by`. Each session carries a compact `client` object, its disposition, and (unless `include_messages=false`) its messages. Media messages expose metadata only (no file URLs). Sessions whose transcript exceeds `max_messages_per_session` are truncated with `has_more_messages=true` — fetch the rest from `/conversations/{session_id}/messages`. Every message names its sender in `sender` (the AI agent, the team member, or the client). Each session also carries `participants` — everyone who replied in that conversation, split into `ai_agents` and `users` with per-participant message counts, covering the whole conversation even when the transcript is truncated or omitted. Use `updated_after` together with `sort_by=updated_at` for incremental sync. ## OpenAPI ````yaml GET /api/v2/public/whatsapp/conversations openapi: 3.1.0 info: title: Dialtu Public API version: '2.0' description: >- Programmatic access to your Dialtu account: schedule AI voice calls, create contacts, push leads into Salesflow pipelines, book calendar appointments and read WhatsApp conversation history. Every request is authenticated with an API key created in the dashboard under **Settings → API Keys**, sent as `Authorization: Bearer pk_...`. servers: - url: https://api.dialtu.com description: Production - url: https://api.stg.dialtu.com description: Staging security: - ApiKeyBearer: [] tags: - name: Calls description: Schedule outbound AI voice calls. - name: Clients description: Create contacts in your account. - name: Salesflow description: Push leads into a pipeline through an API input node. - name: Salesflow pipelines description: Read a pipeline's stages and add, move or remove clients. - name: Calendar description: Check bookable capacity, book appointments and manage waiting lists. - name: WhatsApp description: Read-only conversation history and transcripts. paths: /api/v2/public/whatsapp/conversations: get: tags: - WhatsApp summary: List WhatsApp conversations description: >- List WhatsApp conversations (sessions) with their inline transcripts. Results are a flat, paginated list of sessions ordered by `sort_by`. Each session carries a compact `client` object, its disposition, and (unless `include_messages=false`) its messages. Media messages expose metadata only (no file URLs). Sessions whose transcript exceeds `max_messages_per_session` are truncated with `has_more_messages=true` — fetch the rest from `/conversations/{session_id}/messages`. Every message names its sender in `sender` (the AI agent, the team member, or the client). Each session also carries `participants` — everyone who replied in that conversation, split into `ai_agents` and `users` with per-participant message counts, covering the whole conversation even when the transcript is truncated or omitted. Use `updated_after` together with `sort_by=updated_at` for incremental sync. operationId: listWhatsAppConversations parameters: - in: query name: created_after schema: anyOf: - format: date-time type: string - type: 'null' description: Only sessions created at/after this UTC timestamp. title: Created After required: false description: Only sessions created at/after this UTC timestamp. - in: query name: created_before schema: anyOf: - format: date-time type: string - type: 'null' description: Only sessions created before this UTC timestamp. title: Created Before required: false description: Only sessions created before this UTC timestamp. - in: query name: updated_after schema: anyOf: - format: date-time type: string - type: 'null' description: >- Only sessions updated at/after this UTC timestamp. Use for incremental sync (pull only what changed since the last fetch). title: Updated After required: false description: >- Only sessions updated at/after this UTC timestamp. Use for incremental sync (pull only what changed since the last fetch). - in: query name: client_id schema: anyOf: - type: integer - type: 'null' description: Only sessions belonging to this client. title: Client Id required: false description: Only sessions belonging to this client. - in: query name: search schema: anyOf: - type: string - type: 'null' description: >- Case-insensitive match against client first/last name and the customer phone number. title: Search required: false description: >- Case-insensitive match against client first/last name and the customer phone number. - in: query name: disposition_tag_ids schema: anyOf: - items: type: integer type: array - type: 'null' description: Filter to sessions whose disposition tag is one of these IDs (OR). title: Disposition Tag Ids required: false description: Filter to sessions whose disposition tag is one of these IDs (OR). - in: query name: include_uncategorized schema: default: false description: >- When combined with disposition_tag_ids, also include sessions with no disposition tag. title: Include Uncategorized type: boolean required: false description: >- When combined with disposition_tag_ids, also include sessions with no disposition tag. - in: query name: status schema: anyOf: - type: string - type: 'null' description: >- Session status: new, ai_handling, human_handling, resolved, expired. title: Status required: false description: 'Session status: new, ai_handling, human_handling, resolved, expired.' - in: query name: direction schema: anyOf: - type: string - type: 'null' description: 'Session direction: inbound or outbound.' title: Direction required: false description: 'Session direction: inbound or outbound.' - in: query name: sort_by schema: default: '-created_at' description: >- Sort field, prefix with '-' for descending. One of: created_at, updated_at, last_message_at, client_name. title: Sort By type: string required: false description: >- Sort field, prefix with '-' for descending. One of: created_at, updated_at, last_message_at, client_name. - in: query name: limit schema: default: 20 description: Max sessions per page (max 50). maximum: 50 minimum: 1 title: Limit type: integer required: false description: Max sessions per page (max 50). - in: query name: offset schema: default: 0 description: Number of sessions to skip. minimum: 0 title: Offset type: integer required: false description: Number of sessions to skip. - in: query name: include_messages schema: default: true description: >- Include the inline transcript. Set false for a metadata-only browse. title: Include Messages type: boolean required: false description: Include the inline transcript. Set false for a metadata-only browse. - in: query name: max_messages_per_session schema: default: 500 description: >- Max messages embedded per session (oldest-first). Sessions with more set has_more_messages=true; fetch the rest from the messages endpoint. maximum: 2000 minimum: 1 title: Max Messages Per Session type: integer required: false description: >- Max messages embedded per session (oldest-first). Sessions with more set has_more_messages=true; fetch the rest from the messages endpoint. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PublicWhatsAppHistoryResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/PublicWhatsAppErrorResponse' '401': description: Missing, malformed or revoked API key. content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' examples: missing_header: summary: No Authorization header value: detail: Unauthorized invalid_key: summary: Unknown or revoked key value: detail: Invalid or expired API key. Please check your credentials. '422': description: The request did not match the documented schema. content: application/json: schema: $ref: '#/components/schemas/RequestValidationError' example: detail: - type: missing loc: - body - payload - phone_number msg: Field required '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/PublicWhatsAppErrorResponse' security: - ApiKeyBearer: [] components: schemas: PublicWhatsAppHistoryResponse: description: Paginated list of WhatsApp conversations. properties: status: const: success default: success description: Always `success`. title: Status type: string data: description: Conversations on this page. items: $ref: '#/components/schemas/PublicWhatsAppSessionSchema' title: Data type: array count: description: Total sessions matching the filters. title: Count type: integer limit: description: Page size that was applied. title: Limit type: integer offset: description: Offset that was applied. title: Offset type: integer required: - data - count - limit - offset title: PublicWhatsAppHistoryResponse type: object PublicWhatsAppErrorResponse: description: Public API error response for WhatsApp history operations. properties: status: const: error description: Error status title: Status type: string error_code: description: Machine-readable error code title: Error Code type: string message: description: Human-readable error message title: Message type: string details: anyOf: - additionalProperties: true type: object - type: 'null' description: Additional error details title: Details required: - status - error_code - message title: PublicWhatsAppErrorResponse type: object DetailErrorResponse: description: 'Plain error body: `{"detail": "..."}`. No `error_code` is included.' properties: detail: description: Human-readable reason for the failure. title: Detail type: string required: - detail title: DetailErrorResponse type: object RequestValidationError: title: RequestValidationError type: object description: >- Returned when the request body, query string or path could not be parsed against the documented schema. Fix the listed fields and retry. properties: detail: type: array title: Detail description: One entry per invalid field. items: $ref: '#/components/schemas/RequestValidationErrorItem' required: - detail PublicWhatsAppSessionSchema: description: A WhatsApp conversation (session window) with its transcript. properties: session_id: description: >- Conversation ID; pass it to *List messages in a WhatsApp conversation*. title: Session Id type: integer status: description: '`new`, `ai_handling`, `human_handling`, `resolved`, or `expired`.' title: Status type: string direction: description: '`inbound` or `outbound`.' title: Direction type: string customer_phone_number: description: The customer's WhatsApp number in E.164 format. title: Customer Phone Number type: string client: anyOf: - $ref: '#/components/schemas/PublicWhatsAppClientSchema' - type: 'null' description: Linked client, or null when the number is not matched to a contact. disposition: anyOf: - $ref: '#/components/schemas/PublicWhatsAppDispositionSchema' - type: 'null' description: Disposition tag chosen for the conversation, if any. sentiment: anyOf: - type: string - type: 'null' description: '`positive`, `neutral`, `negative`, or null when not analysed.' title: Sentiment summary: default: '' description: AI-generated summary of the conversation, or empty. title: Summary type: string message_count: default: 0 description: Total conversational messages (excludes tool-execution rows). title: Message Count type: integer has_more_messages: default: false description: True when the transcript was truncated to max_messages_per_session. title: Has More Messages type: boolean created_at: description: When the conversation started (UTC). format: date-time title: Created At type: string updated_at: description: Last change to the conversation (UTC); drives `updated_after`. format: date-time title: Updated At type: string last_message_at: anyOf: - format: date-time type: string - type: 'null' description: Timestamp of the most recent message (UTC). title: Last Message At messages: description: >- Transcript, oldest-first, up to `max_messages_per_session`. Empty when `include_messages=false`. items: $ref: '#/components/schemas/PublicWhatsAppMessageSchema' title: Messages type: array assigned_users: description: >- All people assigned to this customer across their active salesflow pipelines (one assignee per pipeline), most-recently-assigned first. Empty when the customer is unassigned or has no linked client. This is customer-level OWNERSHIP — for who actually replied in this conversation, use participants. items: $ref: '#/components/schemas/PublicWhatsAppAssigneeSchema' title: Assigned Users type: array participants: allOf: - $ref: '#/components/schemas/PublicWhatsAppParticipantsSchema' description: >- Everyone who sent a message in this conversation, split into AI agents and team members, with per-participant counts and first/last timestamps. Always covers the whole conversation — unaffected by include_messages or max_messages_per_session. Only identified senders appear; messages with sender.id = null contribute to no entry. required: - session_id - status - direction - customer_phone_number - created_at - updated_at title: PublicWhatsAppSessionSchema type: object RequestValidationErrorItem: title: RequestValidationErrorItem type: object properties: loc: type: array title: Loc description: >- Where the problem is: the first element is `body`, `query` or `path`, followed by the field path. items: anyOf: - type: string - type: integer msg: type: string title: Msg description: What is wrong with the value. type: type: string title: Type description: >- Machine-readable validation error type, e.g. `missing` or `int_parsing`. required: - loc - msg - type PublicWhatsAppClientSchema: description: Compact client info attached to a session. properties: id: description: Client ID (the same ID used across the public API). title: Id type: integer name: anyOf: - type: string - type: 'null' description: Composed display name. title: Name first_name: anyOf: - type: string - type: 'null' description: Given name. title: First Name last_name: anyOf: - type: string - type: 'null' description: Family name. title: Last Name phone: anyOf: - type: string - type: 'null' description: Phone number in E.164 format. title: Phone email: anyOf: - type: string - type: 'null' description: Email address, when known. title: Email company: anyOf: - type: string - type: 'null' description: Company name, when known. title: Company required: - id title: PublicWhatsAppClientSchema type: object PublicWhatsAppDispositionSchema: description: The disposition tag selected for a session. properties: id: description: Disposition tag ID (usable in `disposition_tag_ids`). title: Id type: integer name: description: Tag name. title: Name type: string required: - id - name title: PublicWhatsAppDispositionSchema type: object PublicWhatsAppMessageSchema: description: A single message in a transcript. properties: id: description: Message ID; use it with `reply_to_id`. title: Id type: integer sender_type: description: customer, ai, human, or system. title: Sender Type type: string sender: $ref: '#/components/schemas/PublicWhatsAppSenderSchema' description: >- The named sender. Use this to attribute a message to a specific AI agent or team member; sender_type only says what kind of party sent it. message_type: description: text, template, media, or system. title: Message Type type: string content: description: >- Message text. For media messages this is the caption or an empty string; for templates, the rendered template body. title: Content type: string timestamp: description: Message timestamp (Meta's original timestamp when available). format: date-time title: Timestamp type: string media: anyOf: - $ref: '#/components/schemas/PublicWhatsAppMediaSchema' - type: 'null' description: Media metadata when `message_type` is `media`; no download URL. reply_to_id: anyOf: - type: integer - type: 'null' description: ID of the message this one quotes, if any. title: Reply To Id required: - id - sender_type - sender - message_type - content - timestamp title: PublicWhatsAppMessageSchema type: object PublicWhatsAppAssigneeSchema: description: A team member assigned to the conversation's customer in a salesflow. properties: id: description: Internal Dialtu user id (matches client.id style). title: Id type: integer name: anyOf: - type: string - type: 'null' description: Composed display name. title: Name email: anyOf: - type: string - type: 'null' description: Email address of the team member. title: Email required: - id title: PublicWhatsAppAssigneeSchema type: object PublicWhatsAppParticipantsSchema: description: Everyone who actually replied in the conversation, split by kind. properties: ai_agents: description: AI agents that replied, busiest first. items: $ref: '#/components/schemas/PublicWhatsAppAgentParticipantSchema' title: Ai Agents type: array users: description: Team members that replied, busiest first. items: $ref: '#/components/schemas/PublicWhatsAppUserParticipantSchema' title: Users type: array title: PublicWhatsAppParticipantsSchema type: object PublicWhatsAppSenderSchema: description: Who sent a message — the named party behind ``sender_type``. properties: type: description: >- ai_agent, user (a Dialtu team member), client (the customer), or system. title: Type type: string id: anyOf: - type: integer - type: 'null' description: >- Internal Dialtu id of the agent, user or client. Null when the sender cannot be identified — messages synced from the WhatsApp Business app and imported history carry no attributable sender. title: Id name: anyOf: - type: string - type: 'null' description: Display name of the sender. title: Name email: anyOf: - type: string - type: 'null' description: >- Email address, when the party has one on file. Populated for type=user and type=client; always null for ai_agent and system. title: Email required: - type title: PublicWhatsAppSenderSchema type: object PublicWhatsAppMediaSchema: description: Media metadata for a media message (no file bytes / no download URL). properties: kind: anyOf: - type: string - type: 'null' description: image, document, video, audio, or sticker. title: Kind mime: anyOf: - type: string - type: 'null' description: IANA MIME type. title: Mime filename: anyOf: - type: string - type: 'null' description: Original filename, if any. title: Filename caption: anyOf: - type: string - type: 'null' description: Media caption, if any. title: Caption title: PublicWhatsAppMediaSchema type: object PublicWhatsAppAgentParticipantSchema: description: An AI agent that produced at least one message in the conversation. properties: id: description: Agent ID. title: Id type: integer name: anyOf: - type: string - type: 'null' description: Agent name. title: Name message_count: default: 0 description: Messages this agent sent in the conversation. title: Message Count type: integer first_message_at: anyOf: - format: date-time type: string - type: 'null' description: Timestamp of the agent's first message (UTC). title: First Message At last_message_at: anyOf: - format: date-time type: string - type: 'null' description: Timestamp of the agent's last message (UTC). title: Last Message At required: - id title: PublicWhatsAppAgentParticipantSchema type: object PublicWhatsAppUserParticipantSchema: description: A team member who sent at least one message in the conversation. properties: id: description: User ID. title: Id type: integer name: anyOf: - type: string - type: 'null' description: Display name. title: Name email: anyOf: - type: string - type: 'null' description: Email address. title: Email message_count: default: 0 description: Messages this person sent in the conversation. title: Message Count type: integer first_message_at: anyOf: - format: date-time type: string - type: 'null' description: Timestamp of the person's first message (UTC). title: First Message At last_message_at: anyOf: - format: date-time type: string - type: 'null' description: Timestamp of the person's last message (UTC). title: Last Message At required: - id title: PublicWhatsAppUserParticipantSchema type: object securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: pk_... description: >- API key created in the dashboard under **Settings → API Keys**. Send it as `Authorization: Bearer pk_...`. ````