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

# Launch a broadcast

> Queues a template broadcast to a list of phone numbers. Every recipient
is written to the database and handed to the send queue before the call
returns, so the `202` survives a restart. Poll
`GET /broadcasts/{id}` for progress.

Recipients are capped at **1000 per request**. A number that is not a
valid phone number is dropped and counted in `rejected`. A contact who
has opted out of marketing is dropped silently and is not counted in
`accepted`. Duplicates of the same contact are collapsed.

Requires the `broadcasts:send` scope.




## OpenAPI

````yaml /openapi.yaml post /broadcasts
openapi: 3.1.0
info:
  title: Watx API
  version: '1'
  description: |
    The Watx public REST API. Send WhatsApp messages, manage contacts and
    segments, read conversations and messages, launch broadcasts, and register
    webhook endpoints.

    Every request authenticates with a workspace API key sent as a bearer
    token. A key acts on exactly one workspace and can only do what its scopes
    allow. Each operation below names the scope it requires.
  contact:
    name: Watx support
    email: support@watx.in
servers:
  - url: https://api.watx.in/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Account
    description: Check which workspace a key belongs to and what it can do.
  - name: Messages
    description: Send a WhatsApp message to a phone number.
  - name: Contacts
    description: Create, read, update and list contacts.
  - name: Conversations
    description: Read conversations and their messages.
  - name: Broadcasts
    description: Launch a template broadcast and follow its progress.
  - name: Segments
    description: Named audiences — static lists and saved filters.
  - name: Webhooks
    description: Register endpoints that receive events from your workspace.
paths:
  /broadcasts:
    post:
      tags:
        - Broadcasts
      summary: Launch a broadcast
      description: |
        Queues a template broadcast to a list of phone numbers. Every recipient
        is written to the database and handed to the send queue before the call
        returns, so the `202` survives a restart. Poll
        `GET /broadcasts/{id}` for progress.

        Recipients are capped at **1000 per request**. A number that is not a
        valid phone number is dropped and counted in `rejected`. A contact who
        has opted out of marketing is dropped silently and is not counted in
        `accepted`. Duplicates of the same contact are collapsed.

        Requires the `broadcasts:send` scope.
      operationId: createBroadcast
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBroadcastRequest'
            example:
              name: September offer
              template_name: september_offer
              template_language: en_US
              recipients:
                - to: '+919876543210'
                  params:
                    - Priya
                - to: '+919876543211'
                  params:
                    - Arun
      responses:
        '202':
          description: The broadcast was accepted and queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BroadcastAccepted'
              example:
                data:
                  broadcast_id: 4f8e2c10-77b9-4d3a-9e12-5a6b7c8d9e0f
                  status: queued
                  total_recipients: 2
                  accepted: 2
                  rejected: 0
        '400':
          description: |
            A missing template name, an empty or oversized recipient list, no
            recipient with a usable phone number, every recipient opted out, or
            WhatsApp not connected (`whatsapp_not_configured`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: bad_request
                  message: >-
                    A broadcast is capped at 1000 recipients per request; split
                    larger sends
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CreateBroadcastRequest:
      type: object
      required:
        - template_name
        - recipients
      properties:
        name:
          type: string
          description: A name for the broadcast. Defaults to `API broadcast (<template>)`.
        template_name:
          type: string
          description: The approved template to send.
        template_language:
          type: string
          default: en_US
        recipients:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            $ref: '#/components/schemas/BroadcastRecipient'
    BroadcastAccepted:
      type: object
      properties:
        broadcast_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - queued
        total_recipients:
          type: integer
          description: How many recipients were queued. Same as `accepted`.
        accepted:
          type: integer
          description: Recipients written and handed to the send queue.
        rejected:
          type: integer
          description: Recipients dropped because the number was unusable.
    Error:
      type: object
      description: |
        Every failure uses this shape. Branch on `error.code`, which is stable;
        `error.message` is written for people and may be reworded.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: |
                One of `bad_request`, `invalid_request`, `unauthorized`,
                `forbidden`, `not_found`, `rate_limited`, `internal`, or a
                domain code such as `whatsapp_not_configured`, `meta_error`,
                `template_malformed`, `plan_limit_reached`,
                `subscription_lapsed`.
              example: bad_request
            message:
              type: string
              example: '''phone'' is required'
    BroadcastRecipient:
      type: object
      required:
        - to
      properties:
        to:
          type: string
          description: The recipient's phone number.
          example: '+919876543210'
        params:
          type: array
          description: This recipient's body values, in placeholder order.
          items:
            type: string
  responses:
    Unauthorized:
      description: |
        The key is missing, malformed, unknown, revoked or expired. All four
        answer the same way.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Missing or invalid API key
    PaymentRequired:
      description: |
        The workspace has used up this plan limit for the month, or its
        subscription has lapsed. Reads keep working; the things that spend do
        not.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key is valid but was not granted the scope this operation requires.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: This API key is missing the 'messages:send' scope
    RateLimited:
      description: |
        More than 120 requests in a minute for this key. `Retry-After` says how
        many seconds to wait.
      headers:
        Retry-After:
          description: Seconds until the window resets.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per window.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left in this window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix time in seconds when the window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded for this API key
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |
        Your workspace API key, created in **Settings → API keys**, sent as
        `Authorization: Bearer <key>`. New keys start with `watx_live_`; keys
        issued before the rename start with `converse360_live_` and still work.

````