---
operation: Bot.contactsConnection
kind: query
graphql_type: Bot
role: Agent
reference_url: https://chatfuel.com/docs/public-api/contacts#how-to-search-and-read-contacts
lang: en
---

# Bot.contactsConnection

Paginated search, up to 500 per page, optionally filtered by a segment and sorted by an attribute.

```graphql
contactsConnection(platforms: [Platform!]!, first: Int!, before: ContactSearchCursor, after: ContactSearchCursor, segment: SegmentInput, orderBy: ContactSearchOrderByInput): ContactConnection!
```

- Kind: query (field of `Bot`, read through `bot(id:)`)
- Role: Agent
- Reference: [Contacts API Reference › How to search and read contacts](https://chatfuel.com/docs/public-api/contacts#how-to-search-and-read-contacts)

---

The reference section that defines it, from [Contacts API Reference](https://chatfuel.com/docs/public-api/contacts#how-to-search-and-read-contacts):

## How to search and read contacts [#how-to-search-and-read-contacts]

```graphql
type Bot {
  # Agent. One contact by ID.
  contact(id: ContactID!): Contact!
  # Agent. Paginated search, up to 500 per page, optionally filtered by a segment and sorted by an attribute.
  contactsConnection(
    platforms: [Platform!]!          # whatsapp, instagram, facebook, tiktok, widget
    first: Int!
    before: ContactSearchCursor
    after: ContactSearchCursor
    segment: SegmentInput
    orderBy: ContactSearchOrderByInput   # { orderBy: <attribute name>, direction: Asc | Desc }
  ): ContactConnection!
  # Agent. Number of contacts matching the platforms and segment.
  contactsCount(platforms: [Platform!]!, segment: SegmentInput): Int!
  contactsTotalCount(platforms: [Platform!]!, segment: SegmentInput): Int!
}
```

`Contact` is an interface; WhatsApp contacts are `WhatsappContact` with an extra `phone` field, and there are similar types for the other channels. Every contact has:

```graphql
query Contact($botID: BotID!, $contactID: ContactID!) {
  bot(id: $botID) {
    contact(id: $contactID) {
      id
      name
      note
      updatedAt
      salesStageV2              # New, Sorting, Ready, WorkingOn, Won, Lost
      lastConversationMessageTime
      unreadMessagesCount
      unhandledSwitchToHuman    # handed to a human and not opened yet
      assignee {
        ... on PublicUserAccount { id name accountType }
        ... on FuelyAIAssignee { __typename }
      }
      attributes(names: ["email", "city"]) {
        attr { name type }
        value {
          ... on BotAttributeValueString { stringValue }
          ... on BotAttributeValueDouble { doubleValue }
          ... on BotAttributeValueBoolean { booleanValue }
          ... on BotAttributeValueDatetime { datetimeValue }
        }
      }
      ... on WhatsappContact { phone }
    }
  }
}
```

---

Other operations on the same page:

- [`Bot.contact`](https://chatfuel.com/docs/api/v1/operations/Bot.contact): One contact by ID.
- [`Bot.contactsCount`](https://chatfuel.com/docs/api/v1/operations/Bot.contactsCount): Number of contacts matching the platforms and segment.
- [`Bot.contactsTotalCount`](https://chatfuel.com/docs/api/v1/operations/Bot.contactsTotalCount)

Before the first request: [Public API Authentication and Tokens](https://chatfuel.com/docs/api/v1/page?path=public-api/authentication), [Making Public API Requests](https://chatfuel.com/docs/api/v1/page?path=public-api/requests), [Public API Errors and Error Codes](https://chatfuel.com/docs/api/v1/page?path=public-api/errors).