Skip to documentation
Developer docsPOST /broadcasts

Endpoint

POST /api/v1/broadcasts

Queue a broadcast campaign from manual recipients, contacts, an existing broadcast list, CSV import, or Google Sheets. The endpoint returns immediately with a broadcast id and run id while workers prepare and send the campaign.

Required scope

Your API key must allow broadcasts:create. Existing unrestricted keys continue to work.

Request fields

  • namestring
    Campaign name shown in the dashboard.
  • source_typestring
    Use manual, google-sheets, contacts, broadcast-list, or csv-upload.
  • source_definitionobject
    Recipient source settings. Manual recipients use the standard fields name, cc, and whatsapp_no.
  • messagestring
    Text body when not sending a template.
  • templateobject | null
    Approved template reference and runtime bindings. Pass id or name; TechUpServices resolves the approved template schema server-side.
  • sender_phone_number_idstring
    Optional sender override if your account owns multiple numbers.
  • scheduled_atISO datetime
    Optional future send time.
  • delivery_modelive | dry_run
    Defaults to live.
  • lead_tracking.enabledboolean
    When true, replies can be assigned to the selected lead tab if the conversation has no existing lead status.
  • lead_tracking.lead_status_iduuid
    Lead tab id to apply on replies.
  • client_referencestring
    Optional reference echoed in the response.

Source types

manual is best when your website already has the audience in its database. Send recipients directly in the API request using name, cc, and whatsapp_no.

google-sheets reads from a connected Google Sheet. Use the same base columns: name, cc, and whatsapp_no.

contacts sends to existing TechUpServices contact IDs.

broadcast-list sends to an existing TechUpServices broadcast list ID.

csv-upload sends from a previously uploaded CSV import. Create the CSV import first, then pass its import ID here.

Template bindings

External websites should identify the approved template and provide bindings. Do not send WhatsApp components; the API resolves the template schema and builds Meta components safely.

Use { "field": "name" } to read from recipient fields, or { "value": "Fixed text" } for a literal value.

Supported scopes are body, header, and buttons. Footer variables are rejected because WhatsApp template footers are static at send time.

{
  "template": {
    "name": "follow_up_template",
    "language": "en_US",
    "bindings": {
      "body": {
        "1": { "field": "name" },
        "2": { "field": "preview_url" }
      },
      "header": {
        "1": { "field": "city" }
      },
      "buttons": {
        "0": { "field": "preview_url" }
      }
    }
  }
}

Scheduling

To schedule a broadcast, pass scheduled_at as a top-level ISO datetime. Include a timezone offset so the send time is unambiguous.

For India time, use YYYY-MM-DDTHH:mm:ss+05:30, for example 2026-07-12T10:30:00+05:30.

Omit scheduled_at to send as soon as the queue worker picks up the broadcast. If the timestamp is already in the past, the broadcast is treated as ready to send immediately.

{
  "scheduled_at": "2026-07-12T10:30:00+05:30"
}

{
  "name": "Template broadcast",
  "source_type": "manual",
  "source_definition": {
    "type": "manual",
    "recipients": [
      {
        "name": "Dental Kraft",
        "cc": "91",
        "whatsapp_no": "9999999999",
        "fields": {
          "preview_url": "https://cardmart.in/dental-kraft-pune-5fab0f",
          "city": "Pune"
        }
      }
    ]
  },
  "template": {
    "name": "follow_up_template",
    "language": "en_US",
    "bindings": {
      "body": {
        "1": { "field": "name" },
        "2": { "field": "preview_url" }
      }
    }
  },
  "scheduled_at": "2026-07-12T10:30:00+05:30"
}

Success response

{
  "request_id": "broadcastreq_2f0f6...",
  "account_id": "...",
  "client_reference": "external-db-campaign-001",
  "broadcast_id": "...",
  "run_id": "...",
  "status": "queued",
  "total_recipients": 1
}