openapi: 3.2.0
info:
  description: Close CRM REST API
  title: Close Activities.whatsapp Messages API
  version: 1.0.0
servers:
- url: https://api.close.com/api/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: activities.whatsapp_messages
  externalDocs:
    url: https://developer.close.com/api/resources/activities/whatsapp
paths:
  /activity/whatsapp_message/:
    get:
      operationId: activities.whatsapp_messages_list
      tags:
      - activities.whatsapp_messages
      summary: List or filter all WhatsAppMessage activities
      description: Filter by `external_whatsapp_message_id` to find messages to update or delete based on changes in WhatsApp.
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/ActivityFilters_IdInParam'
      - $ref: '#/components/parameters/ActivityFilters_LeadIdParam'
      - $ref: '#/components/parameters/ActivityFilters_ContactIdParam'
      - $ref: '#/components/parameters/ActivityFilters_UserIdParam'
      - $ref: '#/components/parameters/ActivityFilters_OrganizationIdParam'
      - $ref: '#/components/parameters/ActivityFilters_TypeParam'
      - $ref: '#/components/parameters/ActivityFilters_DateCreatedGteParam'
      - $ref: '#/components/parameters/ActivityFilters_DateCreatedLteParam'
      - $ref: '#/components/parameters/ActivityFilters_DateCreatedGtParam'
      - $ref: '#/components/parameters/ActivityFilters_DateCreatedLtParam'
      - $ref: '#/components/parameters/ActivityFilters_ActivityAtGteParam'
      - $ref: '#/components/parameters/ActivityFilters_ActivityAtLteParam'
      - $ref: '#/components/parameters/ActivityFilters_ActivityAtGtParam'
      - $ref: '#/components/parameters/ActivityFilters_ActivityAtLtParam'
      - in: query
        name: external_whatsapp_message_id
        required: false
        schema:
          title: External WhatsApp Message ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - _type: WhatsAppMessage
                  activity_at: '2013-02-01T01:06:35.668000+00:00'
                  attachments: []
                  contact_id: cont_q4xYmlGhA3060dEl0NDJuHRxPMuVjqLn30AFSzh1fRk
                  created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  created_by_name: Stefan Wójcik
                  date_created: '2013-02-01T01:05:04.070000+00:00'
                  date_updated: '2013-02-01T01:06:35.668000+00:00'
                  direction: outgoing
                  external_whatsapp_message_id: '1234567890'
                  id: acti_asjiweURMfsLgKuYGqbQ4Qp7L5a16pQOcDfTgotqDak
                  integration_link: https://example.com/messages/1234567890
                  integration_name: API
                  lead_id: lead_KwD00BYbXCHiPWj68LxFkxaeWuULpZ7awzm6LqeFs0h
                  local_phone: '+16503334444'
                  local_phone_formatted: +1 650-333-444
                  message_html: <p>test</p>
                  message_markdown: test
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  remote_phone: '+18183004000'
                  remote_phone_formatted: +1 818-300-4000
                  response_to_id: acti_asjiweURMfsLgKuYGqbQ4Qp7L5a16pQOcDfTgotqDak
                  source: api
                  text: test
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  updated_by_name: Stefan Wójcik
                  user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  users: []
                has_more: false
              schema:
                type: object
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/WhatsAppMessageActivity'
                    type: array
                  has_more:
                    type: boolean
                required:
                - data
                - has_more
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
    post:
      operationId: activities.whatsapp_messages_create
      tags:
      - activities.whatsapp_messages
      summary: Create a WhatsAppMessage activity
      description: '`external_whatsapp_message_id` must be the ID of the message inside WhatsApp. You can filter by this field to find messages in Close to update or delete based on updates or deletions in WhatsApp.


        `message_markdown` must be the body of the message in the WhatsApp Markdown format. The `message_html` read-only field will return the HTML representation of this message.


        To include an attachment, you must first upload the file to Close using the [Files API](https://developer.close.com/api/resources/files). Then, add an object to the `attachments` array with the following fields: `url`, `filename`, and `content_type`. The `url` should be the URL provided in the `download.url` field of the response from the [Files API](https://developer.close.com/api/resources/files). It must begin with `https://app.close.com/go/file/`.


        `integration_link` (optional) is a URL string that can be provided by the integration partner creating the WhatsApp message. This can be used to link back to the message in the external system.


        `response_to_id` (optional) is the Close activity ID of another WhatsApp message activity (not the WhatsApp native message ID) that this message is replying to. This field creates a thread relationship between messages, allowing you to track conversation flow and message replies within WhatsApp threads. The ID must be a valid WhatsApp message activity ID in Close (e.g., `acti_...`).


        Only WhatsApp Markdown messages and file attachments are supported. No support is provided for Polls, Events, Locations, etc.


        **Important**: The total size of all attachments for a single WhatsApp message activity cannot exceed 25MB.


        When creating a new WhatsApp message with the direction set to `incoming`, you can pass the query parameter `send_to_inbox` with the value of `true` to create a corresponding Inbox Notification for the message.'
      parameters:
      - in: query
        name: send_to_inbox
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            example:
              activity_at: '2016-10-03T16:06:11.167000+00:00'
              contact_id: cont_q4xYmlGhA3060dEl0NDJuHRxPMuVjqLn30AFSzh1fRk
              direction: outgoing
              external_whatsapp_message_id: '1234567890'
              integration_link: https://example.com/messages/1234567890
              lead_id: lead_iuSXNk1x3446ggPVwQS7ynmp8pGRIDieRYiCnuo4yFb
              local_phone: '16503334444'
              message_markdown: test
              remote_phone: '18183004000'
              response_to_id: acti_asjiweURMfsLgKuYGqbQ4Qp7L5a16pQOcDfTgotqDak
            schema:
              $ref: '#/components/schemas/CreateWhatsAppMessage'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                _type: WhatsAppMessage
                activity_at: '2016-10-03T16:06:11.167000+00:00'
                attachments: []
                contact_id: cont_q4xYmlGhA3060dEl0NDJuHRxPMuVjqLn30AFSzh1fRk
                created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                created_by_name: Tobias Fuenke
                date_created: '2016-10-03T16:06:11.167000+00:00'
                date_updated: '2016-10-03T16:06:11.167000+00:00'
                direction: outgoing
                external_whatsapp_message_id: '1234567890'
                id: acti_12358hIUhaklslYoYSbtozZuUTyB2zO2nhm7iVSpZpp
                integration_link: https://example.com/messages/1234567890
                integration_name: API
                lead_id: lead_iuSXNk1x3446ggPVwQS7ynmp8pGRIDieRYiCnuo4yFb
                local_phone: '+16503334444'
                local_phone_formatted: +1 650-333-444
                message_html: <p>test</p>
                message_markdown: test
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                remote_phone: '+18183004000'
                remote_phone_formatted: +1 818-300-4000
                response_to_id: acti_asjiweURMfsLgKuYGqbQ4Qp7L5a16pQOcDfTgotqDak
                source: api
                text: test
                updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                updated_by_name: Tobias Fuenke
                user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                user_name: Tobias Fuenke
                users: []
              schema:
                $ref: '#/components/schemas/WhatsAppMessageActivity'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /activity/whatsapp_message/{id}/:
    get:
      operationId: activities.whatsapp_messages_get
      tags:
      - activities.whatsapp_messages
      summary: Get a single WhatsAppMessage activity
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          content:
            application/json:
              example:
                _type: WhatsAppMessage
                activity_at: '2013-02-01T01:06:35.668000+00:00'
                attachments: []
                contact_id: cont_q4xYmlGhA3060dEl0NDJuHRxPMuVjqLn30AFSzh1fRk
                created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                created_by_name: Stefan Wójcik
                date_created: '2013-02-01T01:05:04.070000+00:00'
                date_updated: '2013-02-01T01:06:35.668000+00:00'
                direction: outgoing
                external_whatsapp_message_id: '1234567890'
                id: acti_asjiweURMfsLgKuYGqbQ4Qp7L5a16pQOcDfTgotqDak
                integration_link: https://example.com/messages/1234567890
                integration_name: API
                lead_id: lead_KwD00BYbXCHiPWj68LxFkxaeWuULpZ7awzm6LqeFs0h
                local_phone: '+16503334444'
                local_phone_formatted: +1 650-333-444
                message_html: <p>test</p>
                message_markdown: test
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                remote_phone: '+18183004000'
                remote_phone_formatted: +1 818-300-4000
                response_to_id: acti_asjiweURMfsLgKuYGqbQ4Qp7L5a16pQOcDfTgotqDak
                source: api
                text: test
                updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                updated_by_name: Stefan Wójcik
                user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                users: []
              schema:
                $ref: '#/components/schemas/WhatsAppMessageActivity'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
    put:
      operationId: activities.whatsapp_messages_update
      tags:
      - activities.whatsapp_messages
      summary: Update a WhatsAppMessage activity
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              message_markdown: Updated content.
            schema:
              $ref: '#/components/schemas/UpdateWhatsAppMessage'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                _type: WhatsAppMessage
                activity_at: '2013-02-20T06:39:57.266000+00:00'
                attachments: []
                contact_id: cont_q4xYmlGhA3060dEl0NDJuHRxPMuVjqLn30AFSzh1fRk
                created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                created_by_name: Bruce Wayne
                date_created: '2013-02-20T06:39:57.266000+00:00'
                date_updated: '2013-02-20T06:41:59.846000+00:00'
                direction: outgoing
                external_whatsapp_message_id: '1234567890'
                id: acti_kwWA3rOfy4BnaZ8QQk3RIIAz51dU9ayiluy1s961Oiw
                integration_link: null
                integration_name: API
                lead_id: lead_s6vHFTK1TSRoH6otXOexWDO9jM4xyb1kELHDoU7Fdsp
                local_phone: '+16503334444'
                local_phone_formatted: +1 650-333-444
                message_html: <p>Updated content.</p>
                message_markdown: Updated content.
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                remote_phone: '+18183004000'
                remote_phone_formatted: +1 818-300-4000
                response_to_id: null
                source: api
                text: test
                updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                updated_by_name: Bruce Wayne
                user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                user_name: Bruce Wayne
                users: []
              schema:
                $ref: '#/components/schemas/WhatsAppMessageActivity'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
    delete:
      operationId: activities.whatsapp_messages_delete
      tags:
      - activities.whatsapp_messages
      summary: Delete a WhatsAppMessage activity
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
components:
  parameters:
    ActivityFilters_DateCreatedGteParam:
      in: query
      name: date_created__gte
      required: false
      schema:
        title: Date Created (>=)
        anyOf:
        - type: string
          format: date-time
        - type: string
          format: date
    ActivityFilters_ActivityAtLteParam:
      in: query
      name: activity_at__lte
      required: false
      schema:
        title: Activity At (<=)
        anyOf:
        - type: string
          format: date-time
        - type: string
          format: date
    ActivityFilters_TypeParam:
      description: Filter by activity type, e.g. Call (comma-separated)
      in: query
      name: _type
      required: false
      schema:
        title: Type
        default: null
        anyOf:
        - type: array
          items:
            type: string
        - type: 'null'
    ActivityFilters_OrganizationIdParam:
      in: query
      name: organization_id
      required: false
      schema:
        title: Organization ID
        default: null
        anyOf:
        - type: string
        - type: 'null'
    ActivityFilters_LeadIdParam:
      description: Filter by lead IDs (comma-separated)
      in: query
      name: lead_id
      required: false
      schema:
        title: Lead ID
        default: null
        anyOf:
        - type: array
          items:
            type: string
        - type: 'null'
    ActivityFilters_ActivityAtLtParam:
      in: query
      name: activity_at__lt
      required: false
      schema:
        title: Activity At (<)
        anyOf:
        - type: string
          format: date-time
        - type: string
          format: date
    ActivityFilters_ActivityAtGteParam:
      in: query
      name: activity_at__gte
      required: false
      schema:
        title: Activity At (>=)
        anyOf:
        - type: string
          format: date-time
        - type: string
          format: date
    ActivityFilters_UserIdParam:
      description: Filter by user IDs (comma-separated)
      in: query
      name: user_id
      required: false
      schema:
        title: User ID
        default: null
        anyOf:
        - type: array
          items:
            type: string
        - type: 'null'
    ActivityFilters_ContactIdParam:
      description: Filter by contact IDs (comma-separated)
      in: query
      name: contact_id
      required: false
      schema:
        title: Contact ID
        default: null
        anyOf:
        - type: array
          items:
            type: string
        - type: 'null'
    LimitParam:
      description: Number of results to return.
      in: query
      name: _limit
      required: false
      schema:
        default: 100
        type: integer
    SkipParam:
      description: Number of results to skip before returning, for pagination.
      in: query
      name: _skip
      required: false
      schema:
        default: 0
        type: integer
    ActivityFilters_IdInParam:
      description: Filter by activity IDs (comma-separated)
      in: query
      name: id__in
      required: false
      schema:
        title: ID In
        default: null
        anyOf:
        - type: array
          items:
            type: string
        - type: 'null'
    FieldsParam:
      description: Comma-separated list of fields to include in the response.
      in: query
      name: _fields
      required: false
      schema:
        type: string
    ActivityFilters_DateCreatedLtParam:
      in: query
      name: date_created__lt
      required: false
      schema:
        title: Date Created (<)
        anyOf:
        - type: string
          format: date-time
        - type: string
          format: date
    ActivityFilters_ActivityAtGtParam:
      in: query
      name: activity_at__gt
      required: false
      schema:
        title: Activity At (>)
        anyOf:
        - type: string
          format: date-time
        - type: string
          format: date
    ActivityFilters_DateCreatedGtParam:
      in: query
      name: date_created__gt
      required: false
      schema:
        title: Date Created (>)
        anyOf:
        - type: string
          format: date-time
        - type: string
          format: date
    ActivityFilters_DateCreatedLteParam:
      in: query
      name: date_created__lte
      required: false
      schema:
        title: Date Created (<=)
        anyOf:
        - type: string
          format: date-time
        - type: string
          format: date
  schemas:
    WhatsAppAttachmentData:
      title: WhatsAppAttachmentData
      type: object
      properties:
        content_type:
          title: Content Type
          type: string
        filename:
          title: Filename
          type: string
        url:
          title: Url
          type: string
      required:
      - content_type
      - filename
      - url
    UpdateWhatsAppMessage:
      title: UpdateWhatsAppMessage
      type: object
      properties:
        activity_at:
          title: Activity At
          type: string
          format: date-time
        attachments:
          title: Attachments
          type: array
          items:
            $ref: '#/components/schemas/WhatsAppAttachmentData'
        contact_id:
          title: Contact ID
          type: string
        direction:
          $ref: '#/components/schemas/CommunicationDirection'
        integration_link:
          title: Integration Link
          anyOf:
          - type: string
            format: uri
            minLength: 1
            maxLength: 2083
          - type: 'null'
        local_phone:
          title: Local Phone
          type: string
        message_markdown:
          title: Message Markdown
          type: string
        remote_phone:
          title: Remote Phone
          type: string
        response_to_id:
          title: Response To ID
          anyOf:
          - type: string
          - type: 'null'
        user_id:
          title: User ID
          type: string
      additionalProperties: false
    WhatsAppMessageActivity:
      title: WhatsAppMessageActivity
      type: object
      properties:
        _type:
          title: Type
          type: string
        activity_at:
          title: Activity At
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
        attachments:
          title: Attachments
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        contact_id:
          title: Contact ID
          anyOf:
          - type: string
          - type: 'null'
        created_by:
          title: Created By
          anyOf:
          - type: string
          - type: 'null'
        created_by_name:
          title: Created By Name
          default: null
          anyOf:
          - type: string
          - type: 'null'
        date_created:
          title: Date Created
          type: string
          format: date-time
        date_updated:
          title: Date Updated
          type: string
          format: date-time
        direction:
          $ref: '#/components/schemas/CommunicationDirection'
        external_whatsapp_message_id:
          title: External WhatsApp Message ID
          type: string
        id:
          title: ID
          type: string
        integration_link:
          title: Integration Link
          anyOf:
          - type: string
          - type: 'null'
        integration_name:
          title: Integration Name
          anyOf:
          - type: string
          - type: 'null'
        lead_id:
          title: Lead ID
          anyOf:
          - type: string
          - type: 'null'
        local_phone:
          title: Local Phone
          type: string
        local_phone_formatted:
          title: Local Phone Formatted
          type: string
        message_html:
          title: Message HTML
          type: string
        message_markdown:
          title: Message Markdown
          type: string
        organization_id:
          title: Organization ID
          type: string
        remote_phone:
          title: Remote Phone
          type: string
        remote_phone_formatted:
          title: Remote Phone Formatted
          type: string
        response_to_id:
          title: Response To ID
          anyOf:
          - type: string
          - type: 'null'
        sequence_id:
          title: Sequence ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
        sequence_name:
          title: Sequence Name
          default: null
          anyOf:
          - type: string
          - type: 'null'
        sequence_subscription_id:
          title: Sequence Subscription ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
        source:
          $ref: '#/components/schemas/CreationSource'
        text:
          title: Text
          type: string
        updated_by:
          title: Updated By
          anyOf:
          - type: string
          - type: 'null'
        updated_by_name:
          title: Updated By Name
          default: null
          anyOf:
          - type: string
          - type: 'null'
        user_id:
          title: User ID
          anyOf:
          - type: string
          - type: 'null'
        user_name:
          title: User Name
          default: null
          anyOf:
          - type: string
          - type: 'null'
        users:
          title: Users
          type: array
          items:
            type: string
      required:
      - _type
      - activity_at
      - contact_id
      - created_by
      - date_created
      - date_updated
      - direction
      - external_whatsapp_message_id
      - id
      - integration_link
      - integration_name
      - lead_id
      - local_phone
      - local_phone_formatted
      - message_html
      - message_markdown
      - organization_id
      - remote_phone
      - remote_phone_formatted
      - response_to_id
      - source
      - text
      - updated_by
      - user_id
      - users
    CreationSource:
      title: CreationSource
      type: string
      enum:
      - ui
      - api
      - import
      - clipper
      - email
      - suggestion
      - segment-integration
      - customerio-integration
      - calendly-integration
      - ai
      - whatsapp
      - webform
    CommunicationDirection:
      title: CommunicationDirection
      description: Direction of communication. Outgoing means the communication flowing from the user to the lead/contact. Inbound means the opposite.
      type: string
      enum:
      - incoming
      - outgoing
    CreateWhatsAppMessage:
      title: CreateWhatsAppMessage
      type: object
      properties:
        activity_at:
          title: Activity At
          type: string
          format: date-time
        attachments:
          title: Attachments
          type: array
          items:
            $ref: '#/components/schemas/WhatsAppAttachmentData'
        contact_id:
          title: Contact ID
          type: string
        direction:
          $ref: '#/components/schemas/CommunicationDirection'
        external_whatsapp_message_id:
          title: External WhatsApp Message ID
          type: string
        integration_link:
          title: Integration Link
          default: null
          anyOf:
          - type: string
            format: uri
            minLength: 1
            maxLength: 2083
          - type: 'null'
        lead_id:
          title: Lead ID
          type: string
        local_phone:
          title: Local Phone
          type: string
        message_markdown:
          title: Message Markdown
          type: string
        remote_phone:
          title: Remote Phone
          type: string
        response_to_id:
          title: Response To ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
        user_id:
          title: User ID
          anyOf:
          - type: string
          - type: 'null'
      required:
      - activity_at
      - contact_id
      - direction
      - external_whatsapp_message_id
      - lead_id
      - local_phone
      - message_markdown
      - remote_phone
      additionalProperties: false
    Attachment:
      title: Attachment
      type: object
      properties:
        content_type:
          title: Content Type
          anyOf:
          - type: string
          - type: 'null'
        filename:
          title: Filename
          anyOf:
          - type: string
          - type: 'null'
        size:
          title: Size
          anyOf:
          - type: integer
          - type: 'null'
        thumbnail_url:
          title: Thumbnail URL
          anyOf:
          - type: string
          - type: 'null'
        url:
          title: URL
          type: string
      required:
      - content_type
      - filename
      - size
      - url
  securitySchemes:
    ApiKeyAuth:
      description: Use your API key as the username and leave the password empty.
      scheme: basic
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://app.close.com/oauth2/authorize/
          scopes:
            all.full_access: Full access to all resources
            offline_access: Request a refresh token
          tokenUrl: https://api.close.com/oauth2/token/
      type: oauth2