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

# Add recipients (batch)

> Bulk-add recipients to a draft broadcast.

**Constraints:**
- Accepts up to 1,000 recipients per request
- Broadcast must be in draft status
- Phone numbers are normalized to E.164 format without + prefix

**Template Parameters:**
- Array format for positional parameters: `["Param1", "Param2"]`
- Object format for named parameters with support for media headers:
  ```json
  {
    "first_name": "Alicia",
    "discount_code": "JULY25",
    "header_url": "https://example.com/image.jpg",
    "header_filename": "promo.jpg"
  }
  ```




## OpenAPI

````yaml api/legacy/openapi-platform.yaml post /whatsapp_broadcasts/{broadcast_id}/recipients
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/{broadcast_id}/recipients:
    post:
      tags:
        - WhatsApp Broadcasts
      summary: Add recipients (batch)
      description: |
        Bulk-add recipients to a draft broadcast.

        **Constraints:**
        - Accepts up to 1,000 recipients per request
        - Broadcast must be in draft status
        - Phone numbers are normalized to E.164 format without + prefix

        **Template Parameters:**
        - Array format for positional parameters: `["Param1", "Param2"]`
        - Object format for named parameters with support for media headers:
          ```json
          {
            "first_name": "Alicia",
            "discount_code": "JULY25",
            "header_url": "https://example.com/image.jpg",
            "header_filename": "promo.jpg"
          }
          ```
      operationId: addBroadcastRecipients
      parameters:
        - name: broadcast_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recipients
              properties:
                recipients:
                  type: array
                  maxItems: 1000
                  items:
                    $ref: '#/components/schemas/WhatsappBroadcastRecipientInput'
            examples:
              positional_params:
                summary: Recipients with positional parameters
                value:
                  recipients:
                    - phone_number: '+14155550123'
                      template_parameters:
                        - John
                        - 50% off
                    - phone_number: '+14155550124'
                      template_parameters:
                        - Jane
                        - 40% off
              named_params:
                summary: Recipients with named parameters
                value:
                  recipients:
                    - phone_number: '+14155550123'
                      template_parameters:
                        first_name: Alicia
                        discount_code: JULY25
                        expiry: '2025-07-31'
                        cta_text: Shop now
                        cta_url: https://example.com
                    - phone_number: '+14155550124'
                      template_parameters:
                        first_name: Bob
                        discount_code: JULY30
                        expiry: '2025-07-31'
                        cta_text: Shop now
                        cta_url: https://example.com
              with_contact_id:
                summary: Recipients using contact IDs
                value:
                  recipients:
                    - whatsapp_contact_id: 3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d
                      template_parameters:
                        - Contact Name
                        - Code123
              media_header:
                summary: Recipients with media header template
                value:
                  recipients:
                    - phone_number: '+14155550123'
                      template_parameters:
                        first_name: Alicia
                        header_url: https://example.com/promo.jpg
                        header_filename: promo.jpg
                        discount_code: JULY25
      responses:
        '201':
          description: Recipients added (with summary of successes/failures)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RecipientBatchResponse'
              examples:
                all_success:
                  summary: All recipients added successfully
                  value:
                    data:
                      added: 500
                      duplicates: 0
                      errors: []
                partial_success:
                  summary: Partial success with some errors
                  value:
                    data:
                      added: 495
                      duplicates: 5
                      errors:
                        - >-
                          Recipient 3: template parameters invalid - Template
                          requires 2 parameters but 1 provided
                        - 'Recipient 7: invalid phone number format'
                        - >-
                          Recipient 12: template parameters invalid - Missing
                          required parameter 'first_name'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Broadcast not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_draft:
                  summary: Broadcast not in draft status
                  value:
                    error: Cannot add recipients to broadcast in sending status
                over_limit:
                  summary: Batch over 1000 recipients
                  value:
                    error: Cannot add more than 1000 recipients per request
                malformed_payload:
                  summary: Malformed request payload
                  value:
                    error: Recipients array is required
components:
  schemas:
    WhatsappBroadcastRecipientInput:
      type: object
      description: Recipient input for batch add
      properties:
        phone_number:
          type: string
          example: '+14155550123'
          description: Phone number (can be omitted if whatsapp_contact_id is provided)
        whatsapp_contact_id:
          type: string
          format: uuid
          description: Existing WhatsApp contact ID (optional)
        template_parameters:
          oneOf:
            - type: array
              items:
                type: string
              example:
                - Param1
                - Param2
            - type: object
              additionalProperties: true
              example:
                first_name: Alicia
                discount_code: JULY25
                expiry: '2025-07-31'
                cta_text: Shop now
                cta_url: https://example.com
          description: Template parameters as array (positional) or object (named)
    RecipientBatchResponse:
      type: object
      description: Response from batch recipient add operation
      properties:
        added:
          type: integer
          example: 500
          description: Number of recipients successfully added
        duplicates:
          type: integer
          example: 5
          description: Number of duplicate recipients skipped
        errors:
          type: array
          items:
            type: string
          example:
            - >-
              Recipient 3: template parameters invalid - Template requires 2
              parameters...
            - 'Recipient 7: invalid phone number format'
          description: Array of error messages for failed recipients
    Error:
      type: object
      properties:
        error:
          type: string
          example: Resource not found
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your project API key

````