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

# Preview campaign engagement segment

> Counts and samples the customers who engaged (or not) with WhatsApp Official campaigns, without saving anything. Customers who got several of the campaigns count once, and engaging with any of them counts as engaged. Failed, cancelled, and unsent messages never count as received. breakdown splits everyone the campaigns tried to reach into engaged, not engaged, and not received, so one preview answers both lists. Find the campaign IDs in GET /v1/template-campaigns.



## OpenAPI

````yaml /openapi.en.json get /v1/segments/campaign-engagement/preview
openapi: 3.1.0
info:
  title: Bevits API
  version: 1.0.0
  description: >-
    Public API for querying CRM, purchase, and automation data from a Bevits
    organization, creating automations as drafts for review and activation,
    creating WhatsApp Official campaigns as drafts, and building customer
    segments and tags.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.bevits.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: System
    description: API availability.
  - name: Identity
    description: Organization and API key identity.
  - name: Customers
    description: Customers and their relationships.
  - name: Segments
    description: Customer segments.
  - name: Purchases
    description: Purchases imported from integrations.
  - name: CRM data
    description: Tags and attribute definitions.
  - name: Automations
    description: Automation flows.
  - name: Campaigns
    description: Email campaigns.
  - name: Account and brand
    description: Account context, brand identity, and images.
  - name: Recipes
    description: Ready-made automations created from recipes, with undo.
  - name: Email templates
    description: Creating and importing email templates.
  - name: Events
    description: Custom events sent by the store and their types.
paths:
  /v1/segments/campaign-engagement/preview:
    get:
      tags:
        - Segments
      summary: Preview campaign engagement segment
      description: >-
        Counts and samples the customers who engaged (or not) with WhatsApp
        Official campaigns, without saving anything. Customers who got several
        of the campaigns count once, and engaging with any of them counts as
        engaged. Failed, cancelled, and unsent messages never count as received.
        breakdown splits everyone the campaigns tried to reach into engaged, not
        engaged, and not received, so one preview answers both lists. Find the
        campaign IDs in GET /v1/template-campaigns.
      operationId: previewCampaignEngagementSegment
      parameters:
        - name: campaign_ids
          in: query
          required: true
          description: WhatsApp Official campaign IDs (tcp_...), comma-separated. Up to 50.
          schema:
            type: string
          example: tcp_8f2k1m,tcp_3j9x0a
        - name: engagement
          in: query
          required: true
          description: >-
            engaged: read the message or clicked one of its links. not_engaged:
            the message was delivered and they neither read nor clicked.
            received: the message was delivered.
          schema:
            type: string
            enum:
              - engaged
              - not_engaged
              - received
        - name: purchases
          in: query
          description: >-
            Keeps customers with no (none) or at least one (any) completed
            purchase in the window. Requires purchases_from.
          schema:
            type: string
            enum:
              - none
              - any
        - name: purchases_from
          in: query
          description: >-
            Start of the purchase window (inclusive), in ISO 8601 with a
            timezone.
          schema:
            type: string
            format: date-time
        - name: purchases_to
          in: query
          description: >-
            End of the purchase window (exclusive), in ISO 8601 with a timezone.
            Without it, the window is open-ended.
          schema:
            type: string
            format: date-time
        - name: only_site_base
          in: query
          description: >-
            If true (default), leaves out customers who belong only to physical
            units, as brand campaigns do.
          schema:
            type: boolean
            default: true
        - name: sample_size
          in: query
          description: Number of customers in the sample.
          schema:
            type: integer
            minimum: 0
            maximum: 20
            default: 5
      responses:
        '200':
          $ref: '#/components/responses/CampaignEngagementPreview'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    CampaignEngagementPreview:
      description: Engagement segment preview. Nothing was saved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CampaignEngagementPreview'
    InvalidRequest:
      description: Invalid route parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing, invalid, expired, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authentication_error
              message: Invalid API key.
              request_id: req_07f6cdc3c20249d6afcd90b4
    ValidationError:
      description: A parameter failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: validation_error
              message: Invalid query parameters.
              param: limit
              request_id: req_07f6cdc3c20249d6afcd90b4
    RateLimited:
      description: Request limit exceeded.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CampaignEngagementPreview:
      type: object
      required:
        - object
        - customer_count
        - reachable_count
        - breakdown
        - campaigns
        - sample
        - snapshot_at
      properties:
        object:
          type: string
          const: campaign_engagement_preview
        customer_count:
          type: integer
          minimum: 0
          description: Customers who match the criteria.
        reachable_count:
          type: integer
          minimum: 0
          description: >-
            Of those, the ones a WhatsApp send can reach (with a phone and not
            opted out).
        breakdown:
          $ref: '#/components/schemas/CampaignEngagementBreakdown'
        campaigns:
          type: array
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: string
                pattern: ^tcp_[A-Za-z0-9_-]+$
              name:
                type: string
        sample:
          type: array
          items:
            type: object
            required:
              - object
              - id
            properties:
              object:
                type: string
                const: customer
              id:
                type: string
                pattern: ^cus_[A-Za-z0-9_-]+$
              name:
                type: string
              phone:
                type: string
        snapshot_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    RateLimitErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          required:
            - retry_after
          properties:
            retry_after:
              type: integer
              minimum: 1
              description: Seconds before retrying.
    CampaignEngagementBreakdown:
      type: object
      required:
        - engaged
        - not_engaged
        - not_received
      properties:
        engaged:
          type: integer
          minimum: 0
        not_engaged:
          type: integer
          minimum: 0
        not_received:
          type: integer
          minimum: 0
    Error:
      type: object
      required:
        - type
        - message
        - request_id
      properties:
        type:
          type: string
          enum:
            - authentication_error
            - conflict
            - internal_error
            - invalid_request
            - not_found
            - permission_denied
            - rate_limited
            - validation_error
        code:
          type: string
          description: >-
            Stable, machine-readable reason within type, such as
            invalid_event_name. Present when the error has a named reason.
        message:
          type: string
        param:
          type: string
          description: >-
            Full path of the offending field, such as customer.email or
            events[3].name.
        suggestion:
          type: string
          description: A value that would be accepted, when there is an obvious one.
        request_id:
          type: string
          pattern: ^req_[a-f0-9]{24}$
  headers:
    RetryAfter:
      description: Seconds before retrying.
      schema:
        type: integer
        minimum: 1
    RateLimitLimit:
      description: Total limit for the current window.
      schema:
        type: integer
        example: 600
    RateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
        example: 599
    RateLimitReset:
      description: UTC instant when the current window ends.
      schema:
        type: string
        format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bvt_live_...
      description: API key created in the organization settings.

````

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