> ## Documentation Index > Fetch the complete documentation index at: https://help.withallo.com/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > Returns a paginated list of conversations grouped by contact phone number, sorted by most recent activity. **Required scope:** `CONVERSATIONS_READ` This endpoint is paginated. Use `page` and `size` query parameters to control results. See [Pagination](/en/v2/api-reference/guides/pagination). ## Field notes | Field | Null when | | ------------------------- | --------------------------------------------------------------- | | `last_item.summary` | SMS items, or calls where AI summary is not yet available | | `last_item.duration` | SMS items (only applies to calls) | | `last_item.result` | SMS items (only applies to calls) | | `last_item.recording_url` | Recording disabled, call not answered, or SMS items | | `last_item.transcript` | Not requested via `extend=transcript`, or SMS items | | `last_item.content` | Call items (only applies to SMS) | | `last_item.status` | Call items (only applies to SMS) | | `last_item.contacts` | Empty array when no matching contact exists in the address book | ### Extend parameter The `extend` query parameter accepts a comma-separated list of optional fields to include. Currently supported: | Value | Effect | | ------------ | --------------------------------------------------- | | `transcript` | Include full call transcripts on conversation items | Passing an unsupported value returns a `400` error with code `UNSUPPORTED_EXTEND_VALUE`. ## OpenAPI ````yaml GET /v2/api/conversations openapi: 3.0.3 info: title: Allo API description: >- Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages. All requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation. version: 1.0.0 contact: name: Allo Support servers: - url: https://api.withallo.com description: Production server security: [] tags: - name: Summary Templates description: >- Manage call summary templates that control how AI-generated call summaries are structured for your team. - name: Webhooks description: >- Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret. - name: Calls description: >- Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number. - name: Contacts description: >- Search and retrieve contact information with sorting and pagination. Includes engagement level tracking. - name: SMS description: Send SMS messages to phone numbers using your Allo numbers. - name: Phone Numbers description: Retrieve information about your Allo phone numbers. - name: Analytics description: Pre-computed call metrics, team performance, and outbound dial funnel - name: CRM description: Manage people, companies, and deals in your CRM. paths: /v2/api/conversations: get: tags: - Conversations summary: List conversations description: >- Returns a paginated list of conversations grouped by contact phone number, sorted by most recent activity. operationId: listConversations parameters: - name: allo_number in: query required: true description: >- Filter by Allo number (E.164). Required — list your numbers with GET /v2/api/numbers to find the right one. schema: type: string example: '+14155550100' - name: last_activity_since in: query description: >- Only return conversations with activity after this timestamp (ISO 8601). Ideal for incremental sync. schema: type: string format: date-time example: '2026-04-20T10:00:00Z' - name: unread in: query schema: type: boolean - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Size' - $ref: '#/components/parameters/Extend' responses: '200': description: List of conversations content: application/json: schema: allOf: - type: object properties: data: type: array items: $ref: '#/components/schemas/ConversationSummary' - $ref: '#/components/schemas/PaginatedResponse' example: data: - contact_number: '+14155551234' contacts: - id: cnt-abc123 name: Sarah Johnson company: id: com-xyz789 name: Acme Corp deals: - id: dea-def456 name: Enterprise Plan status: open last_activity: '2026-04-21T14:30:00Z' last_item: id: cll-abc123 type: CALL direction: INBOUND date: '2026-04-21T14:30:00Z' summary: Customer called about upgrading their plan. result: ANSWERED duration: 145 pagination: page: 1 size: 20 total_count: 156 total_pages: 8 has_more: true '401': $ref: '#/components/responses/ApiUnauthorized' '429': $ref: '#/components/responses/ApiRateLimited' security: - ApiKeyAuth: [] components: parameters: Page: name: page in: query description: Page number (1-indexed) schema: type: integer default: 1 minimum: 1 Size: name: size in: query description: Results per page schema: type: integer default: 20 minimum: 1 maximum: 100 Extend: name: extend in: query description: 'Comma-separated optional fields. Supported: `transcript`' schema: type: string example: transcript schemas: ConversationSummary: type: object properties: contact_number: type: string example: '+14155551234' contacts: type: array items: $ref: '#/components/schemas/Contact' last_activity: type: string format: date-time last_item: $ref: '#/components/schemas/ConversationItem' PaginatedResponse: type: object properties: pagination: $ref: '#/components/schemas/Pagination' Contact: type: object properties: id: type: string example: cnt-abc123 name: type: string example: Sarah Johnson company: type: object nullable: true properties: id: type: string example: com-xyz789 name: type: string example: Acme Corp deals: type: array items: type: object properties: id: type: string example: dea-def456 name: type: string example: Enterprise Plan status: type: string enum: - OPEN - WON - LOST ConversationItem: type: object properties: id: type: string example: cll-abc123 type: type: string enum: - CALL - SMS direction: type: string enum: - INBOUND - OUTBOUND allo_number: type: string example: '+14155550100' contact_number: type: string example: '+14155551234' contacts: type: array items: $ref: '#/components/schemas/Contact' user: $ref: '#/components/schemas/UserRef' date: type: string format: date-time duration: type: integer nullable: true result: type: string nullable: true enum: - ANSWERED - VOICEMAIL - TRANSFERRED recording_url: type: string nullable: true summary: type: string nullable: true tags: type: array items: type: string nullable: true transcript: type: array nullable: true items: $ref: '#/components/schemas/TranscriptEntry' content: type: string nullable: true status: type: string nullable: true enum: - PENDING - SENT - DELIVERED - FAILED message_type: type: string nullable: true enum: - SMS - MMS - WHATSAPP Pagination: type: object properties: page: type: integer size: type: integer total_count: type: integer total_pages: type: integer has_more: type: boolean ApiError: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean request_id: type: string retry_after_seconds: type: integer nullable: true UserRef: type: object properties: id: type: string example: usr-abc123 name: type: string example: John email: type: string example: john@acme.com TranscriptEntry: type: object properties: source: type: string enum: - USER - EXTERNAL time: type: string format: date-time text: type: string responses: ApiUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiRateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ````