> ## Documentation Index
> Fetch the complete documentation index at: https://kapso-1adbad2d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create broadcast

> Create a draft WhatsApp broadcast tied to a production WhatsApp config and template.

**Requirements:**
- WhatsApp config must be production type
- Template must be approved and linked to the config




## OpenAPI

````yaml api/legacy/openapi-platform.yaml post /whatsapp_broadcasts
openapi: 3.0.3
info:
  title: Kapso Platform API
  description: >-
    Build WhatsApp automation into your SaaS. Let your customers connect their
    own WhatsApp Business accounts.
  version: 1.0.0
  contact:
    name: Kapso Support
servers:
  - url: https://app.kapso.ai/api/v1
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /whatsapp_broadcasts:
    post:
      tags:
        - WhatsApp Broadcasts
      summary: Create broadcast
      description: >
        Create a draft WhatsApp broadcast tied to a production WhatsApp config
        and template.


        **Requirements:**

        - WhatsApp config must be production type

        - Template must be approved and linked to the config
      operationId: createWhatsappBroadcast
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - whatsapp_broadcast
              properties:
                whatsapp_broadcast:
                  type: object
                  required:
                    - name
                    - whatsapp_config_id
                    - whatsapp_template_id
                  properties:
                    name:
                      type: string
                      example: July Promo
                      description: Name for this broadcast campaign
                    whatsapp_config_id:
                      type: string
                      format: uuid
                      example: 4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d
                      description: Production WhatsApp config ID
                    whatsapp_template_id:
                      type: string
                      format: uuid
                      example: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d
                      description: Approved template ID linked to the config
            examples:
              basic:
                summary: Basic broadcast
                value:
                  whatsapp_broadcast:
                    name: July Promo
                    whatsapp_config_id: 4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d
                    whatsapp_template_id: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d
      responses:
        '201':
          description: Broadcast created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WhatsappBroadcast'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_config:
                  summary: Invalid config/template relationship
                  value:
                    error: Template not linked to config
                missing_users:
                  summary: No project users
                  value:
                    error: No users found for project
components:
  schemas:
    WhatsappBroadcast:
      type: object
      description: WhatsApp broadcast campaign
      properties:
        id:
          type: string
          format: uuid
          example: 5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c
        name:
          type: string
          example: July Promo
        status:
          type: string
          enum:
            - draft
            - sending
            - completed
            - failed
          example: draft
          description: Current broadcast status
        started_at:
          type: string
          format: date-time
          nullable: true
          example: '2025-07-15T10:00:00Z'
        completed_at:
          type: string
          format: date-time
          nullable: true
          example: '2025-07-15T11:30:00Z'
        created_at:
          type: string
          format: date-time
          example: '2025-07-14T15:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-07-15T11:30:00Z'
        whatsapp_config_id:
          type: string
          format: uuid
          example: 4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d
          description: WhatsApp config ID
        whatsapp_template:
          $ref: '#/components/schemas/BasicWhatsappTemplate'
        total_recipients:
          type: integer
          example: 123
          description: Total number of recipients
        sent_count:
          type: integer
          example: 100
        failed_count:
          type: integer
          example: 23
        delivered_count:
          type: integer
          example: 90
        read_count:
          type: integer
          example: 75
        responded_count:
          type: integer
          example: 12
        pending_count:
          type: integer
          example: 0
        response_rate:
          type: number
          format: float
          example: 12
          description: Percentage of recipients who responded
        stats:
          $ref: '#/components/schemas/WhatsappBroadcastStats'
    Error:
      type: object
      properties:
        error:
          type: string
          example: Resource not found
    BasicWhatsappTemplate:
      type: object
      description: Basic WhatsApp template info (nested in broadcast response)
      properties:
        id:
          type: string
          format: uuid
          example: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d
        name:
          type: string
          example: july_promo_template
        language_code:
          type: string
          example: en_US
        category:
          type: string
          enum:
            - MARKETING
            - UTILITY
            - AUTHENTICATION
          example: MARKETING
        status:
          type: string
          enum:
            - approved
            - pending
            - rejected
          example: approved
    WhatsappBroadcastStats:
      type: object
      description: Broadcast delivery statistics
      properties:
        total:
          type: integer
          example: 123
        sent:
          type: integer
          example: 100
        failed:
          type: integer
          example: 23
        delivered:
          type: integer
          example: 90
        read:
          type: integer
          example: 75
        responded:
          type: integer
          example: 12
        pending:
          type: integer
          example: 0
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your project API key

````