> ## 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.

# Attach file to the scheduled message

> Attaches an image, video, document or audio file to the schedule. Use it when you want to replace
only the file. The attachment can also be sent along with the schedule's `POST` and `PUT`.

Audio is converted to OGG/Opus, the format WhatsApp accepts as a voice message.
A new attachment replaces the previous one, and the old file's space goes back to your storage quota.

The same editing rule applies: only schedules in `PENDENTE` or `ERRO` accept attachments.



## OpenAPI

````yaml /api-reference/openapi.en.yaml post /schedules/{id}/media
openapi: 3.0.3
info:
  title: Connecta DESK Public API
  version: 1.0.0
  description: >-
    Public API of Connecta DESK, available at `/api/v1`. Access uses a token
    generated in the tokens module. Each token has permissions per **module ×
    method**, and every list read is paginated.


    ## Authentication


    ```

    Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

    ```


    The token belongs to a **company**, not to a user. The company used is
    always the token's company, so sending `companyId` in the body has no
    effect. A missing, invalid, revoked or expired token gets the same `401`
    response.


    ## Order of checks


    1. **token** → `401`

    2. **active company** → `403`

    3. **API enabled on the plan** → `403 ERR_API_NOT_ENABLED` (does not apply
    to on-premise)

    4. **company rate limit** → `429`

    5. **token permission** → `403 ERR_API_FORBIDDEN_SCOPE`


    ## User ids


    Every user id in the API is the user's id **in this company**, the same one
    `GET /users` returns. This applies to what the API returns (`user.id`,
    `assignedTo.id`, `userCreated.id`) and to what it accepts (`userId`,
    `userIds`, `assignedToUserId` and the `{id}` in user routes).


    The same person can work in several companies, with a different name and
    profile in each one, and has a different id in each company.


    An id that does not belong to this company returns `404`, with the same
    message as an id that does not exist.


    ## Pagination


    Every list `GET` is paginated. The `meta` contains only `page`, `perPage`
    and `hasMore`, without the total number of records. To go through
    everything, keep advancing `page` while `hasMore` is `true`.


    ## Idempotency


    Optional on `POST`/`PUT`, through the `Idempotency-Key` header. If you
    repeat the call with the same key and the same body, you get the stored
    response (with `Idempotent-Replay: true`). With the same key and a different
    body, the response is `409`.
servers:
  - url: https://api.connectadesk.com/api/v1
    description: Production
security:
  - apiToken: []
tags:
  - name: contacts
    description: Contact records, extra fields and marketing source.
  - name: tickets
    x-displayName: Tickets
    description: Opening, transferring, closing and wrap-up of tickets.
  - name: messages
    description: Asynchronous sending and reading of messages.
  - name: tags
    description: Tags and their link to tickets.
  - name: queues
    description: Service queues and their agents.
  - name: wrapups
    description: Wrap-up types.
  - name: users
    description: Agents and administrators.
  - name: schedules
    description: Scheduled messages.
  - name: quick-messages
    description: Quick replies.
  - name: campaigns
    description: Bulk sending.
  - name: crm
    description: Boards, stages, cards and metrics.
  - name: channels
    description: Channels (read only).
  - name: reports
    description: Reports and dashboards.
  - name: products
    description: Product catalog, categories and sales performance.
  - name: custom-fields
    description: Custom fields for contacts and cards, plus company-wide global variables.
  - name: profiles
    description: Company permission profiles (read only).
  - name: webchat
    description: >-
      Native webchat from your own system: open a visitor session, send and read
      messages. The token needs the `webchat` scope (GET and POST).
paths:
  /schedules/{id}/media:
    parameters:
      - $ref: '#/components/parameters/idParam'
    post:
      tags:
        - schedules
      summary: Attach file to the scheduled message
      description: >-
        Attaches an image, video, document or audio file to the schedule. Use it
        when you want to replace

        only the file. The attachment can also be sent along with the schedule's
        `POST` and `PUT`.


        Audio is converted to OGG/Opus, the format WhatsApp accepts as a voice
        message.

        A new attachment replaces the previous one, and the old file's space
        goes back to your storage quota.


        The same editing rule applies: only schedules in `PENDENTE` or `ERRO`
        accept attachments.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Schedule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The schedule's current status does not allow attachments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    idParam:
      name: id
      in: path
      required: true
      schema:
        type: integer
      example: 1042
  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: >-
            Full contact data, with tags, custom fields and marketing fields.
            You do not need to call `GET /contacts/{id}` to complete the list.
          allOf:
            - $ref: '#/components/schemas/Contact'
        user:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Display name.
        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'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Fixed error code, so your system can handle each case.
              example: ERR_API_FORBIDDEN_SCOPE
            message:
              type: string
            details: {}
    Contact:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Display name.
        number:
          type: string
        numberCountry:
          type: string
          nullable: true
          description: >-
            Country of the number, as an ISO 3166-1 alpha-2 code. Inferred from
            the country code when the number is saved through the 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: The contact is a group, not a person.
        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: Display name.
              color:
                type: string
                description: Color in hexadecimal, with `#`.
                example: '#6941C6'
        customFields:
          type: array
          description: >-
            Contact custom fields that are filled in. Always included in the
            response, as an empty list when the contact has none.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
        lastChannel:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Display name.
            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: >-
        Value of a custom field, together with the field's definition. This way
        you do not need to call `GET /custom-fields` to find out what field 91
        is.
      properties:
        key:
          type: string
          nullable: true
          description: >-
            Fixed identifier of the field. Use it to point to the field when
            saving values, because the `name` can be renamed in the panel and
            the integration would stop working without warning.
        value:
          type: string
          description: Value filled in for the field, in the format defined by its type.
        customFieldId:
          type: integer
          description: Id of the custom field definition.
          example: 91
        name:
          type: string
          nullable: true
          description: Display name.
        type:
          type: string
          nullable: true
          description: Field type, which defines the format accepted for the value.
      example:
        key: plano
        value: Ouro
        customFieldId: 91
        name: Plano
        type: select
  responses:
    BadRequest:
      description: Invalid request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_VALIDATION
              message: O campo `number` é obrigatório.
    NotFound:
      description: >-
        The resource does not exist or belongs to another company. For security,
        the response is the same in both cases.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_NOT_FOUND
              message: Registro não encontrado.
    UnprocessableEntity:
      description: >-
        The body is well formed, but a required field is missing or a value is
        not accepted. For example, `application` other than `contact`/`card`, an
        empty `orderedIds` or a blank `name`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_VALIDATION
              message: >-
                O parâmetro `application` é obrigatório e aceita "contact" ou
                "card".
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: API token in the `sk_live_…` format.

````

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