> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar agendamentos



## OpenAPI

````yaml /api-reference/openapi.yaml get /schedules
openapi: 3.0.3
info:
  title: Connecta DESK API pública
  version: 1.0.0
  description: >
    API pública do Connecta DESK, disponível em `/api/v1`. O acesso é feito com
    um token gerado no módulo de tokens. Cada token tem permissões por **módulo
    × método**, e toda leitura de lista é paginada.


    ## Autenticação


    ```

    Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

    ```


    O token pertence a uma **empresa**, e não a um usuário. A empresa usada é
    sempre a do token, então enviar `companyId` no corpo não tem efeito. Token
    ausente, inválido, revogado ou expirado recebe a mesma resposta `401`.


    ## Ordem de verificação


    1. **token** → `401`

    2. **empresa ativa** → `403`

    3. **API habilitada no plano** → `403 ERR_API_NOT_ENABLED` (não se aplica a
    on-premise)

    4. **rate limit da empresa** → `429`

    5. **permissão do token** → `403 ERR_API_FORBIDDEN_SCOPE`


    ## Ids de usuário


    Todo id de usuário na API é o id do usuário **nesta empresa**, o mesmo que
    `GET /users` devolve. Vale para o que a API responde (`user.id`,
    `assignedTo.id`, `userCreated.id`) e para o que ela aceita (`userId`,
    `userIds`, `assignedToUserId` e o `{id}` das rotas de usuário).


    A mesma pessoa pode trabalhar em várias empresas, com nome e perfil
    diferentes em cada uma, e tem um id diferente em cada empresa.


    Um id que não pertence a esta empresa responde `404`, com a mesma mensagem
    de um id inexistente.


    ## Paginação


    Todo `GET` de lista é paginado. O `meta` traz apenas `page`, `perPage` e
    `hasMore`, sem o total de registros. Para percorrer tudo, avance `page`
    enquanto `hasMore` for `true`.


    ## Idempotência


    Opcional em `POST`/`PUT`, pelo header `Idempotency-Key`. Se você repetir a
    chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada (com
    `Idempotent-Replay: true`). Com a mesma chave e um corpo diferente, a
    resposta é `409`.
servers:
  - url: https://api.connectadesk.com/api/v1
    description: Produção
security:
  - apiToken: []
tags:
  - name: contacts
    description: Cadastro de contatos, campos extras e origem de marketing.
  - name: tickets
    x-displayName: Conversas
    description: Abertura, transferência, encerramento e qualificação de conversas.
  - name: messages
    description: Envio assíncrono e leitura de mensagens.
  - name: tags
    description: Tags e vínculo com atendimentos.
  - name: queues
    description: Filas de atendimento e seus atendentes.
  - name: wrapups
    description: Tipos de qualificação.
  - name: users
    description: Atendentes e administradores.
  - name: schedules
    description: Mensagens programadas.
  - name: quick-messages
    description: Respostas rápidas.
  - name: campaigns
    description: Disparos em massa.
  - name: crm
    description: Painéis, etapas, cards e indicadores.
  - name: channels
    description: Canais (somente leitura).
  - name: reports
    description: Relatórios e dashboards.
  - name: products
    description: Catálogo de produtos, categorias e desempenho nas vendas.
  - name: custom-fields
    description: >-
      Campos personalizados de contato e de card, e variáveis globais da
      empresa.
  - name: profiles
    description: Perfis de permissões da empresa (somente leitura).
  - name: webchat
    description: >-
      Webchat nativo pelo seu sistema: abrir sessão de um visitante, enviar e
      ler mensagens. O token precisa do escopo `webchat` (GET e POST).
paths:
  /schedules:
    get:
      tags:
        - schedules
      summary: Listar agendamentos
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/perPage'
        - name: search
          in: query
          description: Busca no texto da mensagem ou no contato.
          schema:
            type: string
          example: lembrete
        - name: contactId
          in: query
          description: Somente agendamentos destinados a este contato.
          schema:
            type: integer
          example: 1042
        - name: userId
          in: query
          description: >-
            Somente agendamentos criados por este usuário. Use o id do usuário
            nesta empresa, o mesmo que `GET /users` devolve. A mesma pessoa tem
            um id diferente em cada empresa em que trabalha.
          schema:
            type: integer
          example: 3
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Schedule'
                  meta:
                    $ref: '#/components/schemas/PageMeta'
components:
  parameters:
    page:
      name: page
      in: query
      description: Número da página, começando em 1. Um valor inválido é tratado como 1.
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    perPage:
      name: perPage
      in: query
      description: >-
        Quantidade de itens por página. O máximo depende do ambiente (padrão
        100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 50
  schemas:
    Schedule:
      type: object
      properties:
        id:
          type: integer
        body:
          type: string
        sendAt:
          type: string
          format: date-time
          example: '2026-09-15T09:00:00.000Z'
        sentAt:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          nullable: true
        contact:
          type: object
          nullable: true
          description: >-
            Dados completos do contato, com tags, campos personalizados e campos
            de marketing. Você não precisa chamar `GET /contacts/{id}` para
            completar a listagem.
          allOf:
            - $ref: '#/components/schemas/Contact'
        user:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Nome exibido.
        channelId:
          type: integer
          nullable: true
          example: 4
        mediaPath:
          type: string
          nullable: true
        mediaName:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      example:
        id: 318
        body: Oi {{name}}, sua reserva vence amanhã!
        sendAt: '2026-08-20T13:00:00.000Z'
        sentAt: null
        status: pending
        contact:
          id: 842
          name: Maria Silva
          number: '5511987654321'
          numberCountry: BR
          email: maria.silva@exemplo.com.br
          code: CLI-00842
          cpfCnpj: '12345678909'
          origin: site
          profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg
          isGroup: false
          instagramUsername: maria.silva
          lid: null
          sourceUrl: https://loja.exemplo.com.br/promo
          sourceId: '23851234567890123'
          headline: Coleção de inverno
          mediaType: image
          mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg
          utmSource: instagram
          utmMedium: cpc
          utmCampaign: inverno-2026
          utmId: '6543210987'
          fbclid: IwAR0xYzAbC123
          gclid: null
          ctwaClid: null
          tags:
            - id: 3
              name: Cliente VIP
              color: '#6941C6'
          customFields:
            - key: plano
              value: Ouro
              customFieldId: 91
              name: Plano
              type: select
          lastChannel:
            id: 11
            name: Instagram Loja
            type: instagram
          createdAt: '2026-07-14T13:22:05.412Z'
          updatedAt: '2026-08-18T09:41:17.883Z'
        user:
          id: 3
          name: Gabriel Goulart
        channelId: 11
        mediaPath: null
        mediaName: null
        createdAt: '2026-08-18T15:10:00.000Z'
        updatedAt: '2026-08-18T15:10:00.000Z'
    PageMeta:
      type: object
      required:
        - page
        - perPage
        - hasMore
      properties:
        page:
          type: integer
          example: 1
        perPage:
          type: integer
          example: 20
        hasMore:
          type: boolean
          description: Indica se há mais registros além desta página.
          example: true
      example:
        page: 1
        perPage: 20
        hasMore: true
    Contact:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Nome exibido.
        number:
          type: string
        numberCountry:
          type: string
          nullable: true
          description: >-
            País do número, no padrão ISO 3166-1 alfa-2. Deduzido do DDI quando
            o número é gravado pela API.
          example: BR
        email:
          type: string
          nullable: true
          example: marina@exemplo.com.br
        code:
          type: string
          nullable: true
        cpfCnpj:
          type: string
          nullable: true
          example: '12345678909'
        origin:
          type: string
          nullable: true
        profilePicUrl:
          type: string
          nullable: true
          example: https://cdn.exemplo.com.br/avatar/1042.jpg
        isGroup:
          type: boolean
          description: O contato é um grupo, e não uma pessoa.
        instagramUsername:
          type: string
          nullable: true
          example: marina.alves
        lid:
          type: string
          nullable: true
          example: '178452961234567'
        sourceUrl:
          type: string
          nullable: true
          example: https://loja.exemplo.com.br/promo
        sourceId:
          type: string
          nullable: true
          example: '23851234567890123'
        headline:
          type: string
          nullable: true
          example: Coleção de inverno
        mediaType:
          type: string
          nullable: true
          example: image
        mediaUrl:
          type: string
          nullable: true
          example: https://cdn.exemplo.com.br/anuncios/inverno.jpg
        utmSource:
          type: string
          nullable: true
          example: instagram
        utmMedium:
          type: string
          nullable: true
          example: cpc
        utmCampaign:
          type: string
          nullable: true
          example: inverno-2026
        utmId:
          type: string
          nullable: true
          example: '6543210987'
        fbclid:
          type: string
          nullable: true
          example: IwAR0xYzAbC123
        gclid:
          type: string
          nullable: true
        ctwaClid:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
                description: Nome exibido.
              color:
                type: string
                description: Cor em hexadecimal, com `#`.
                example: '#6941C6'
        customFields:
          type: array
          description: >-
            Campos personalizados de contato preenchidos. Sempre vem na
            resposta, como lista vazia quando o contato não tem nenhum.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
        lastChannel:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Nome exibido.
            type:
              type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      example:
        id: 842
        name: Maria Silva
        number: '5511987654321'
        numberCountry: BR
        email: maria.silva@exemplo.com.br
        code: CLI-00842
        cpfCnpj: '12345678909'
        origin: site
        profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg
        isGroup: false
        instagramUsername: maria.silva
        lid: null
        sourceUrl: https://loja.exemplo.com.br/promo
        sourceId: '23851234567890123'
        headline: Coleção de inverno
        mediaType: image
        mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg
        utmSource: instagram
        utmMedium: cpc
        utmCampaign: inverno-2026
        utmId: '6543210987'
        fbclid: IwAR0xYzAbC123
        gclid: null
        ctwaClid: null
        tags:
          - id: 3
            name: Cliente VIP
            color: '#6941C6'
        customFields:
          - key: plano
            value: Ouro
            customFieldId: 91
            name: Plano
            type: select
        lastChannel:
          id: 11
          name: Instagram Loja
          type: instagram
        createdAt: '2026-07-14T13:22:05.412Z'
        updatedAt: '2026-08-18T09:41:17.883Z'
    CustomFieldValue:
      type: object
      description: >-
        Valor de um campo personalizado, junto com a definição do campo. Assim
        você não precisa chamar `GET /custom-fields` para saber qual é o campo
        91.
      properties:
        key:
          type: string
          nullable: true
          description: >-
            Identificador fixo do campo. Use-o para indicar o campo ao gravar
            valores, porque o `name` pode ser renomeado no painel e a integração
            deixaria de funcionar sem aviso.
        value:
          type: string
          description: Valor preenchido no campo, no formato definido pelo tipo.
        customFieldId:
          type: integer
          description: Id da definição do campo personalizado.
          example: 91
        name:
          type: string
          nullable: true
          description: Nome exibido.
        type:
          type: string
          nullable: true
          description: Tipo do campo, que define o formato aceito no valor.
      example:
        key: plano
        value: Ouro
        customFieldId: 91
        name: Plano
        type: select
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: Token da API no formato `sk_live_…`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.