Skip to main content

Broadcast API - V2

The V2 Broadcasts API uses a payload-variable model. You supply a tabular payload (like a CSV) where each row is a recipient, and the template object maps column names to template variable slots via payload_variable fields with optional fallback values.

See the authentication page for how to obtain a bearer token.

Create a Broadcast​

POST https://api.cuedesk.com/v2/broadcasts
Authorization: Bearer <token>
Content-Type: application/json

Examples​

{
  "name": "Holiday Sale",
  "from": "447576209857",
  "scheduled_at": "2024-06-15T10:00:00Z",
  "valid_until": "2024-12-31T23:59:59Z",
  "client_unique_identifier": "abe120b4-048c-4d00-9c1a-0b01d34c583c",
  "template": {
    "name": "holiday_sale_template",
    "locale": "en",
    "header": {
      "type": "image",
      "payload_variable": "header_image_url",
      "fallback": "https://www.example.com/default-sale.jpg"
    },
    "body": {
      "payload_variables": ["first_name", "discount_code", "expiry_date"],
      "fallbacks": ["Customer", "SALE2024", "31 Dec"]
    },
    "buttons": [
      {
        "index": 0,
        "type": "URL",
        "payload_variable": "tracking_url_suffix",
        "fallback": "default"
      }
    ]
  },
  "payload": [
    {
      "identifier": "447592850122",
      "client_reference": "order-abc-123",
      "first_name": "Alex",
      "discount_code": "ALEX20",
      "expiry_date": "25 Dec",
      "header_image_url": "https://www.example.com/alex-promo.jpg",
      "tracking_url_suffix": "alex-campaign"
    },
    {
      "identifier": "27827134468",
      "client_reference": "order-def-456",
      "first_name": "Jordan",
      "discount_code": "JORDAN15",
      "expiry_date": "30 Dec"
    }
  ]
}

In this example, the second recipient does not have header_image_url or tracking_url_suffix in their payload row, so the fallback values from the template definition will be used instead.

Request Body​

FieldTypeRequiredDescription
namestringNoName of the broadcast (for your reference)
fromstringYesPhone number or channel identifier used as the sender
scheduled_atdatetimeNoISO 8601 timestamp for when to send. Sends immediately if omitted
valid_untildatetimeNoISO 8601 timestamp after which undelivered messages expire. No expiry if omitted
templateobjectYesTemplate definition with payload variable mappings
payloadarrayNoArray of recipient rows. Each row is a key-value map
contact_list_uuidUUIDNoUUID of a pre-uploaded contact list. Alternative to payload
client_unique_identifierstringNoIdempotency key to prevent duplicate broadcasts

Template Object​

The template object defines which template to use and how payload columns map to template variable slots.

FieldTypeRequiredDescription
namestringYesName of the approved WhatsApp template
localestringYesLanguage code (e.g. en, pt_BR)
headerobjectNoHeader variable mapping
bodyobjectNoBody variable mappings
buttonsarrayNoButton variable mappings
cardsarrayNoCard definitions for carousel templates
FieldTypeRequiredDescription
typestringNoHeader media type: image, video, document, or text
payload_variablestringNoPayload column name containing the header value (URL for media, text for text headers)
fallbackstringNoDefault value used when payload_variable is missing from a recipient's row
filenamestringNoFilename for document type headers

Body​

FieldTypeRequiredDescription
payload_variablesarray[string]NoOrdered list of payload column names. Position 0 maps to {{1}}, position 1 maps to {{2}}, etc.
fallbacksarray[string]NoPositional fallback values. Must be the same length as payload_variables if provided

Buttons​

FieldTypeRequiredDescription
indexintegerYesZero-based position of the button in the template
typestringNoButton type: URL, OTP, QUICK_REPLY
payload_variablestringNoPayload column name for the button's dynamic value
fallbackstringNoDefault value when payload_variable is missing

Cards​

FieldTypeRequiredDescription
indexintegerYesZero-based card position. Fully static cards can be omitted
headerobjectNoCard-level header (same structure as above)
bodyobjectNoCard-level body (same structure as above)
buttonsarrayNoCard-level buttons (same structure as above)

Payload​

The payload is an array of objects where each object represents one recipient. Every row must contain an identifier key with the recipient's phone number. All other keys are custom column names referenced by payload_variable in the template definition.

KeyTypeRequiredDescription
identifierstringYesRecipient phone number with country code (no leading +)
client_referencestringNoCustom reference ID for this recipient, returned in webhook status updates (max 255 chars)
(custom keys)stringNoValues for payload variables referenced in the template
danger

If a recipient row is missing a column referenced by a payload_variable and no fallback is defined, a warning will be generated for that recipient.

Response​

202 Accepted​

{
  "broadcast": {
    "uuid": "d3b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
    "name": "Holiday Sale",
    "scheduled_at": "2024-06-15T10:00:00Z",
    "status": "scheduled",
    "created_at": "2024-06-01T12:00:00Z",
    "recipients": 19750
  },
  "warnings": [
    {
      "identifier": "6563546436",
      "errors": [
        "Missing payload variable 'discount_code' with no fallback defined"
      ]
    }
  ]
}
FieldTypeDescription
broadcast.uuidUUIDUnique identifier of the created broadcast
broadcast.namestringBroadcast name
broadcast.scheduled_atdatetimeScheduled send time (null if immediate)
broadcast.statusstringBroadcast status: scheduled, processing, completed, cancelled
broadcast.created_atdatetimeWhen the broadcast was created
broadcast.recipientsintegerTotal number of valid recipients
warningsarrayPer-recipient warnings for validation issues
warnings[].identifierstringRecipient phone number
warnings[].errorsarray[string]Warning messages for this recipient

Error Responses​

400 Bad Request:

{
  "message": "Broadcast could not be created",
  "details": "Template 'holiday_sale_template' not found or not approved"
}

403 Forbidden:

{
  "message": "Forbidden",
  "details": "Channel does not belong to your workspace"
}

422 Unprocessable Entity:

{
  "error": {
    "message": "Validation failed",
    "details": "Template parameter count mismatch",
    "violations": [
      {
        "field": "template.body.payload_variables",
        "rule": "PARAMETER_COUNT_MISMATCH",
        "message": "Template expects 3 body parameters but 2 were provided"
      }
    ]
  }
}