# inbox.conversations_list

Listar conversas da caixa de entrada. Conversas da conta atual, da mais recente à mais antiga, só dos números que o membro pode usar (e, com "só livres e as próprias" ligado, só as sem atendente ou do próprio membro). Filtros combinados com E: `tab` (`mine` = atribuídas a mim; `queue` = abertas sem atendente; `all`), `kind` (`direct` = só individuais; `group` = só grupos), `statusIn` (open, assigned, resolved, closed), `channelId`/`channelIdIn`, `priorityIn`, `unread` (mensagens não lidas), `awaitingReply` (última mensagem é do contato), `unreadByMe` (marcada não lida ou com entrada depois da minha leitura), `lastMessageAfter`/`lastMessageBefore` (ISO, inclusivo), `q` (nome, telefone ou ticket como `#000123` ou `123`). `assignedToIn` e `includeUnassigned` são só para administradores. `origin` diz se o contato veio de anúncio. Paginação por `cursor` (devolvido em `nextCursor`). `total` é a contagem de todas as conversas que casam com os filtros (sem o cursor), só na primeira página; nas seguintes é `null`. `viewAsAttendantId` (só admin) faz `tab: mine` valer para aquele atendente.

- Endpoint: `POST https://app.atomiks.com.br/api/v1/inbox.conversations_list` (corpo JSON)
- Quem pode chamar: membro da conta
- Escopo da chave: `messages:read`
- Grava dados: não
- Pela chave de API: sim
- Ferramenta MCP: `inbox_conversations_list`
- Ficha em JSON: `https://app.atomiks.com.br/api/v1/openapi.json` (operationId `inbox.conversations_list`)

## Entrada

| Campo | Tipo | Obrigatório | Nota |
|---|---|---|---|
| `tab` | "mine" \| "queue" \| "all" | não |  |
| `kind` | "all" \| "direct" \| "group" | não |  |
| `statusIn` | "open" \| "assigned" \| "resolved" \| "closed"[] | não |  |
| `channelId` | string (uuid) | não |  |
| `channelIdIn` | string (uuid)[] | não |  |
| `q` | string | não |  |
| `unread` | boolean | não |  |
| `awaitingReply` | boolean | não |  |
| `unreadByMe` | boolean | não |  |
| `assignedToIn` | string (uuid)[] | não |  |
| `includeUnassigned` | boolean | não |  |
| `priorityIn` | "low" \| "normal" \| "high" \| "urgent"[] | não |  |
| `lastMessageAfter` | string (date-time) | não |  |
| `lastMessageBefore` | string (date-time) | não |  |
| `viewAsAttendantId` | string (uuid) | não |  |
| `archived` | boolean | não |  |
| `cursor` | string | não |  |
| `limit` | integer | não |  |

<details><summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "tab": {
      "type": "string",
      "enum": [
        "mine",
        "queue",
        "all"
      ]
    },
    "kind": {
      "type": "string",
      "enum": [
        "all",
        "direct",
        "group"
      ]
    },
    "statusIn": {
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "open",
          "assigned",
          "resolved",
          "closed"
        ]
      }
    },
    "channelId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "channelIdIn": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "q": {
      "type": "string",
      "maxLength": 80
    },
    "unread": {
      "type": "boolean"
    },
    "awaitingReply": {
      "type": "boolean"
    },
    "unreadByMe": {
      "type": "boolean"
    },
    "assignedToIn": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "includeUnassigned": {
      "type": "boolean"
    },
    "priorityIn": {
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "low",
          "normal",
          "high",
          "urgent"
        ]
      }
    },
    "lastMessageAfter": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "lastMessageBefore": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "viewAsAttendantId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "archived": {
      "type": "boolean"
    },
    "cursor": {
      "type": "string",
      "maxLength": 300
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
```

</details>

## Exemplo

```bash
curl -X POST https://app.atomiks.com.br/api/v1/inbox.conversations_list \
  -H "Authorization: Bearer $ATOMIKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tab":"queue","statusIn":["open","assigned"],"limit":50}'
```

CLI:

```bash
node cli/atomiks.mjs inbox.conversations_list --json '{"tab":"queue","statusIn":["open","assigned"],"limit":50}'
```

MCP: ferramenta `inbox_conversations_list` com a mesma entrada.

## Saída

Sucesso: `{"data": ...}` com o formato abaixo.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "channel": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "whatsapp_cloud",
                  "whatsapp_web"
                ]
              },
              "connectionType": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "coexistence",
                      "new_number",
                      "qr"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "webProvider": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "evolution",
                      "waha"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "displayPhone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "verifiedName": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "kind",
              "connectionType",
              "displayPhone",
              "verifiedName"
            ],
            "additionalProperties": false
          },
          "contact": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "avatarUrl": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "name",
              "phone",
              "avatarUrl"
            ],
            "additionalProperties": false
          },
          "lastMessageAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "lastMessagePreview": {
            "type": [
              "string",
              "null"
            ]
          },
          "lastMessageSender": {
            "type": [
              "string",
              "null"
            ]
          },
          "windowExpiresAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "unreadCount": {
            "type": "number"
          },
          "unreadByMe": {
            "type": "boolean"
          },
          "origin": {
            "type": "string",
            "enum": [
              "ad",
              "organic"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "assigned",
              "resolved",
              "closed"
            ]
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "normal",
              "high",
              "urgent"
            ]
          },
          "assignee": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "id",
                  "name"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "ticket": {
            "type": [
              "string",
              "null"
            ]
          },
          "mutedByMe": {
            "type": "boolean"
          },
          "pinnedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "windowState": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "open",
                  "closing",
                  "closed"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "isGroup": {
            "type": "boolean"
          },
          "groupSubject": {
            "type": [
              "string",
              "null"
            ]
          },
          "archivedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "blockedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "unreadMentionId": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "channel",
          "contact",
          "lastMessageAt",
          "lastMessagePreview",
          "windowExpiresAt",
          "unreadCount",
          "unreadByMe",
          "origin",
          "status",
          "priority",
          "assignee",
          "ticket",
          "mutedByMe",
          "windowState",
          "isGroup",
          "groupSubject"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "total": {
      "type": [
        "number",
        "null"
      ]
    }
  },
  "required": [
    "items",
    "nextCursor",
    "total"
  ],
  "additionalProperties": false
}
```

## Erros

`{"error": {"code", "message", "requestId"}}`. Códigos: `invalid_input` (400), `unauthorized` (401), `forbidden` / `account_pending` / `scope_missing` (403), `not_found` (404), `limit_reached` (409), `internal` (500).