> ## Documentation Index > Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > Returns your conversations, most recently active first (ordered by `lastMessageAt`). A conversation is the thread between one of your numbers and one contact on one channel, and Vobiz creates it with the first message in either direction. ## OpenAPI ````yaml openapi-sms.yaml GET /conversations openapi: 3.0.3 info: title: Vobiz Messaging API description: > Send and receive SMS, MMS and RCS messages, buy messaging numbers, register for US 10DLC and toll-free, run broadcasts, manage conversations, opt-outs and webhooks. **Base URL:** `https://api.vobiz.ai/api/v1/sms` **Authentication:** every request needs the `X-Auth-ID` and `X-Auth-Token` headers. The account is taken from your credentials; you never put an account ID in a path or body. Field names in this API are camelCase. version: '1.0' contact: email: support@vobiz.ai url: https://vobiz.ai servers: - url: https://api.vobiz.ai/api/v1/sms description: Production security: - AuthID: [] AuthToken: [] tags: - name: Messages description: Send messages and inspect their delivery state. - name: Numbers description: >- Messaging-capable numbers on your account, inventory search, purchase and release. - name: Coverage description: Where you can send, per country. - name: Conversations description: Two-way threads between one of your numbers and a contact. - name: Opt-outs description: Numbers that must not receive messages on a channel. - name: Webhooks description: Subscriptions that deliver message and broadcast events to your server. - name: Broadcasts description: Bulk sends from an uploaded recipient list. - name: RCS Senders description: RCS sender (agent) identities and their message templates. - name: 10DLC Brands description: US 10DLC brand registration. - name: 10DLC Campaigns description: US 10DLC campaigns, toll-free verification and supporting documents. paths: /conversations: get: tags: - Conversations summary: List conversations description: >- Returns your conversations, most recently active first (ordered by `lastMessageAt`). A conversation is the thread between one of your numbers and one contact on one channel, and Vobiz creates it with the first message in either direction. The response is a bare JSON array, `[]` when you have none. Page with `limit` and `offset`; when a page returns fewer items than `limit`, you have reached the end. operationId: list-conversations parameters: - name: limit in: query description: >- Maximum number of conversations to return, from `1` to `100`. Defaults to `20`; a value outside that range also returns `20`. schema: type: integer minimum: 1 maximum: 100 default: 20 - name: offset in: query description: >- Number of conversations to skip before the page starts, `0` or greater. Defaults to `0`. Add the page size to it to fetch the next page. schema: type: integer minimum: 0 default: 0 responses: '200': description: A page of conversations. Empty array when none. content: application/json: schema: type: array items: $ref: '#/components/schemas/Conversation' example: - id: c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04 accountId: MA_XXXXXXXX participantA: '+14155550100' participantB: '+14155550123' channel: sms lastMessageAt: '2026-10-16T21:23:51Z' messageCount: 3 unreadCount: 1 createdAt: '2026-10-16T21:23:02Z' - id: 1a9c3e5b-7d2f-4b8a-9c6e-0f4d2b8a6c13 accountId: MA_XXXXXXXX participantA: '+14155550100' participantB: '+14155550124' channel: sms lastMessageAt: '2026-10-16T13:25:41Z' messageCount: 2 unreadCount: 0 lastReadAt: '2026-10-16T21:24:15Z' createdAt: '2026-10-16T13:25:41Z' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/ServerError' x-codeSamples: - lang: typescript label: Node SDK source: > import { VobizClient } from "@vobiz/sdk"; const client = new VobizClient({ apiKey: "MA_XXXXXXXX", authToken: "YOUR_AUTH_TOKEN" }); await client.sms.conversations.listConversations() - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.conversations.list_conversations() - lang: go label: Go SDK source: | import ( "context" vobiz "github.com/vobiz-ai/Vobiz-Go-SDK" "github.com/vobiz-ai/Vobiz-Go-SDK/client" "github.com/vobiz-ai/Vobiz-Go-SDK/option" "github.com/vobiz-ai/Vobiz-Go-SDK/sms" ) c := client.NewClient( option.WithAPIKey("MA_XXXXXXXX"), option.WithAuthToken("YOUR_AUTH_TOKEN"), ) request := &sms.ListConversationsRequest{} c.Sms.Conversations.ListConversations( context.TODO(), request, ) - lang: java label: Java SDK source: | import com.vobiz.api.VobizApiClient; VobizApiClient client = VobizApiClient .builder() .apiKey("MA_XXXXXXXX") .authToken("YOUR_AUTH_TOKEN") .build(); client.sms().conversations().listConversations( ListConversationsRequest .builder() .build() ); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.conversations.list_conversations - lang: csharp label: C# SDK source: > using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Conversations.ListConversationsAsync(new ListConversationsRequest()); - lang: php label: PHP SDK source: > sms->conversations->listConversations( new ListConversationsRequest([]), ); components: schemas: Conversation: type: object description: >- A two-way thread between one of your numbers (or RCS senders) and one contact on one channel. Vobiz creates it with the first message in either direction and adds every later message between the same pair on that channel. properties: id: type: string format: uuid example: c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04 description: >- Unique identifier of the conversation (UUID). Pass it to the conversation endpoints; messages carry it as `conversationId`. accountId: type: string description: Your Vobiz account ID (Auth ID), for example `MA_XXXXXXXX`. example: MA_XXXXXXXX participantA: type: string description: >- Your side of the thread: your number in E.164 format, or the `senderName` of your RCS sender. example: '+14155550100' participantB: type: string description: The contact's phone number in E.164 format. example: '+14155550123' channel: type: string enum: - sms - mms - rcs description: >- Channel the thread runs on: `sms`, `mms` or `rcs`. The same two parties have a separate conversation on each channel. lastMessageAt: type: string format: date-time example: '2026-10-16T21:23:51Z' description: >- Time of the latest message in the thread, sent or received (ISO 8601, UTC). Conversation lists are ordered by it, newest first. messageCount: type: integer example: 3 description: Total number of messages in the thread, in both directions. unreadCount: type: integer description: >- Number of messages added to the thread since it was last marked read. `POST /conversations/{id}/read` resets it to `0`. example: 1 lastReadAt: type: string format: date-time description: >- When the thread was last marked read (ISO 8601, UTC). Omitted until you first call `POST /conversations/{id}/read`. example: '2026-10-17T08:46:55Z' createdAt: type: string format: date-time example: '2026-10-16T21:23:02Z' description: >- When the conversation was created, as an RFC 3339 / ISO 8601 timestamp in UTC. Error: type: object description: >- The body of every error response: a flat object with one `error` string that explains what went wrong. Use the HTTP status code to decide how to handle the error, and log `error` for diagnosis. required: - error properties: error: type: string example: 'recipient has opted out: +14155550123' description: >- Human-readable explanation of the error, for example `phoneNumber is required` or `recipient has opted out: +14155550123`. Branch on the HTTP status code rather than on this text. responses: Unauthorized: description: Missing or invalid `X-Auth-ID` / `X-Auth-Token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing or invalid credentials ServerError: description: Unexpected error. Retry with the same idempotency key where one applies. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal error securitySchemes: AuthID: type: apiKey in: header name: X-Auth-ID description: Your Vobiz account Auth ID (`MA_XXXXXXXX`). AuthToken: type: apiKey in: header name: X-Auth-Token description: Your Vobiz account Auth Token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.