Broadcast API - V1

The Broadcasts API allows you to create and send bulk WhatsApp broadcasts using WhatsApp Templates. It's recommended that you familiarise yourself with WhatsApp Templates before using this API.

Create a Broadcast

Here's an example of how you can send a WhatsApp broadcast using the API. See the authentication page for how to obtain a bearer token.

Request

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

{
  "channel_type": "whatsapp",
  "name": "Holiday Sale",
  "template_name": "holiday_sale_template",
  "locale": "en",
  "valid_until": "2024-12-31T23:59:59Z",
  "scheduled_for": "2024-06-15T10:00:00Z",
  "from": "447576209857",
  "parameters": {
    "header": {
      "type": "image",
      "value": "https://www.example.com/image.jpg"
    },
    "body_order": ["Name", "Time", "Place"],
    "button_order": ["url_1", "url_2"]
  },
  "version": 1,
  "client_unique_identifier": "abe120b4-048c-4d00-9c1a-0b01d34c583c",
  "recipients": [
    {
      "identifier": "447592850122",
      "client_reference": "541d2b80-7569-4774-8798-f89c3378bbfa",
      "parameters": {
        "header": {
          "value": "https://www.example.com/override/image.jpg"
        },
        "body": {
          "Name": "Alex",
          "Place": "City Centre",
          "Time": "18h00"
        },
        "button": {
          "url_1": "url parameter value 1",
          "url_2": "url parameter value 2"
        }
      }
    },
    {
      "identifier": "27827134468",
      "client_reference": "541d2b80-7569-4774-8798-f89c3378bbfa",
      "parameters": {
        "body": {
          "Name": "Jordan",
          "Place": "City Hall",
          "Time": "18h00"
        },
        "button": {
          "url_1": "url parameter value 1",
          "url_2": "url parameter value 2"
        }
      }
    }
  ]
}

Attribute	Type	Description
`channel_type`	Required	Type of channel used to broadcast the message, i.e. `whatsapp`
`name`	Required	Name of the broadcast
`template_name`	Required	Name of the template to be used for the broadcast
`locale`	Optional	language code used for the template. Will default to 'en' for english
`valid_until`	Optional	Datetime until the broadcast is valid (optional, forever if not set)
`scheduled_for`	Optional	The time the Broadcast will be scheduled for (optional, now if not set)
`from`	Required	Phone number or identifier that will be used as the sender
`version`	Optional	API version (default to latest if not set)
`client_unique_identifier`	Optional	Idempotency key that prevents duplicate broadcasts
`parameters`	Optional	Optional parameter values depending on the template: `header`: Specifies the template media type and the parameters for media `type`: Specifies the template media type and the parameters for media `value`: Type of the media, i.e. `image`, `video`, `document` or `text` (default, not required) `body_order`: Array defining the order of body parameters `button_order`: Array defining the order of button parameters `cards`: Array of card definitions for carousel templates. See Carousel Broadcasts for details.
`recipients`	Required	List of contacts with parameters (max 50,000) `identifier`: Contact identifier (i.e. phone number - must be valid with country code excluding the preceding '+' symbol) `client_reference`: Client reference. Optional (max 255 characters) `parameters`: Template parameters for this contact. Optional, depending on the template requirements. `header`: media file value override for each recipient. Default will be the value in the broadcast parameters.header if not set i.e. "https://www.example.com/image.jpg" `body`: Body parameters for the template message body `button`: dynamic url button parameter for the template message `cards`: Per-recipient card parameter values for carousel templates. See Carousel Broadcasts for details.

Responses

202 Accepted

{
  "uuid": "d3b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "status": "scheduled",
  "scheduled_at": "2024-06-15T10:00:00Z",
  "recipients": 19750,
  "rejected_recipients": 250,
  "warnings": {
    "recipients": [
      {
        "identifier": "6563546436",
        "errors": ["error 1", "error 2"]
      }
    ]
  }
}

400 Bad Request

{
  "message": "Broadcast could not be scheduled",
  "details": "Specific validation errors or missing fields"
}

404 Not Found

{
  "message": "Resource not found",
  "details": "Specific validation errors or missing fields"
}

Carousel Broadcasts

Carousel templates allow you to broadcast a horizontally scrollable set of cards in a single WhatsApp message. Each card can have its own media header, personalised body text, and buttons. This is useful for showcasing multiple products, services, or options at scale.

info

Your carousel template must be pre-approved by WhatsApp before you can use it. Each card in the carousel must have the same header type (e.g. all cards must have image headers, or all must have video headers).

Request

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

{
  "channel_type": "whatsapp",
  "name": "Product Showcase",
  "template_name": "product_carousel_template",
  "locale": "en",
  "scheduled_for": "2024-06-15T10:00:00Z",
  "from": "447576209857",
  "parameters": {
    "body_order": ["Name"],
    "cards": [
      {
        "header": {
          "type": "image",
          "value": "https://www.example.com/product1.jpg"
        },
        "body_order": ["product_name", "price"],
        "button_order": ["url_suffix"]
      },
      {
        "header": {
          "type": "image",
          "value": "https://www.example.com/product2.jpg"
        },
        "body_order": ["product_name", "price"],
        "button_order": ["url_suffix"]
      }
    ]
  },
  "recipients": [
    {
      "identifier": "447592850122",
      "client_reference": "541d2b80-7569-4774-8798-f89c3378bbfa",
      "parameters": {
        "body": {
          "Name": "Alex"
        },
        "cards": [
          {
            "header": {
              "value": "https://www.example.com/alex/product1.jpg"
            },
            "body": {
              "product_name": "Running Shoes",
              "price": "$99.00"
            },
            "button": {
              "url_suffix": "running-shoes-123"
            }
          },
          {
            "body": {
              "product_name": "Casual Sneakers",
              "price": "$79.00"
            },
            "button": {
              "url_suffix": "casual-sneakers-456"
            }
          }
        ]
      }
    },
    {
      "identifier": "27827134468",
      "client_reference": "661d2b80-7569-4774-8798-f89c3378bbfb",
      "parameters": {
        "body": {
          "Name": "Jordan"
        },
        "cards": [
          {
            "body": {
              "product_name": "Trail Boots",
              "price": "$120.00"
            },
            "button": {
              "url_suffix": "trail-boots-789"
            }
          },
          {
            "body": {
              "product_name": "Slip-Ons",
              "price": "$49.00"
            },
            "button": {
              "url_suffix": "slip-ons-012"
            }
          }
        ]
      }
    }
  ]
}

Broadcast-level card parameters

The cards array inside parameters defines the structure and default media for each card in the carousel. These settings apply to all recipients unless overridden.

Attribute	Type	Description
`cards[].header`	Optional	Default media header for this card, shared across all recipients. `type`: Media type, i.e. `image` or `video` `value`: URL of the media file
`cards[].body_order`	Optional	Array defining the order of body parameter names for this card. Each name maps to a key in the per-recipient card's `body` object.
`cards[].button_order`	Optional	Array defining the order of button parameter names for this card. Each name maps to a key in the per-recipient card's `button` object.

Per-recipient card parameters

Each recipient's parameters.cards array provides the personalised values for each card. The cards must be in the same order as the broadcast-level cards.

Attribute	Type	Description
`cards[].header`	Optional	Override the card's media URL for this recipient. Only the `value` field is expected (the media type is inherited from the broadcast-level card).
`cards[].body`	Optional	Key-value map of body parameter values for this card. Keys must match the names defined in the broadcast-level card's `body_order`.
`cards[].button`	Optional	Key-value map of button parameter values for this card. Keys must match the names defined in the broadcast-level card's `button_order`. For URL buttons this is the dynamic suffix appended to the button URL.

info

You can combine a template-level body parameter with cards in the same broadcast. For example, if your carousel template has a greeting in the template body above the cards, you can personalise it via the top-level body parameter while also providing per-card values. Note that top-level header and button parameters are not supported on carousel templates -- these are defined per card only.

Validate a Broadcast payload

Here's an example of how you can validate a WhatsApp broadcast requests using the API. See the authentication page for how to obtain a bearer token.

Request

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

{
  "channel_type": "whatsapp",
  "name": "Holiday Sale",
  "template_name": "holiday_sale_template",
  "locale": "en",
  "valid_until": "2024-12-31T23:59:59Z",
  "scheduled_for": "2024-06-15T10:00:00Z",
  "from": "447576209857",
  "parameters": {
    "header": {
      "type": "image",
      "value": "https://www.example.com/image.jpg"
    },
    "body_order": ["Name", "Time", "Place"]
  },
  "version": 1,
  "recipients": [
    {
      "identifier": "447592850122",
      "parameters": {
        "body": {
          "Name": "Alex",
          "Place": "City Centre",
          "Time": "18h00"
        }
      }
    },
    {
      "identifier": "27827134468",
      "parameters": {
        "body": {
          "Name": "Jordan",
          "Place": "City Hall",
          "Time": "18h00"
        }
      }
    }
  ]
}

Attribute	Type	Description
`channel_type`	Required	Type of channel used to broadcast the message, i.e. `whatsapp`
`name`	Required	Name of the broadcast
`template_name`	Required	Name of the template to be used for the broadcast
`locale`	Optional	language code used for the template. Will default to 'en' for english
`valid_until`	Optional	Datetime until the broadcast is valid (optional, forever if not set)
`scheduled_for`	Optional	The time the Broadcast will be scheduled for (optional, now if not set)
`from`	Required	Phone number or identifier that will be used as the sender
`version`	Optional	API version (default to latest if not set)
`parameters`	Optional	Optional parameter values depending on the template: `header`: Specifies the template media type and the parameters for media `type`: Specifies the template media type and the parameters for media `value`: Type of the media, i.e. `image`, `video`, `document` or `text` (default, not required) `cards`: Array of card definitions for carousel templates. See Carousel Broadcasts for details.
`recipients`	Required	List of contacts with parameters (max 20,000) `identifier`: Contact identifier (i.e. phone number - must be valid with country code excluding the preceding '+' symbol) `parameters`: Template parameters for this contact. Optional, depending on the template requirements. `body`: Body parameters for the template message body `cards`: Per-recipient card parameter values for carousel templates. See Carousel Broadcasts for details.

Responses

200 OK

{
  "warnings": {
    "recipients": [
      {
        "identifier": "6563546436",
        "errors": ["error reason 1", "error reason 2"]
      }
    ]
  }
}

400 Bad Request

{
  "message": "Broadcast could not be scheduled",
  "details": "Specific validation errors or missing fields"
}

404 Not Found

{
  "message": "Resource not found",
  "details": "Specific error message"
}

Cancel Broadcast

Request

POST https://api.cuedesk.com/broadcasts/{uuid}/cancel
Authorization: Bearer <token>
Content-Type: application/json

Responses

200 OK

{
  "uuid": "d3b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "status": "cancelled"
}

400 Bad Request

{
  "message": "Broadcast could not be cancelled",
  "details": "Specific validation errors or missing fields"
}

404 Not Found

{
  "message": "Resource not found",
  "details": "Specific validation errors or missing fields"
}

Get Broadcast Details

Request

GET https://api.cuedesk.com/broadcasts/{uuid}
Authorization: Bearer <token>
Content-Type: application/json

Responses

200 OK

{
  "uuid": "d3b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "status": "scheduled",
  "scheduled_at": "2024-06-15T10:00:00Z",
  "recipients": 20000,
  "sent": 15000,
  "delivered": 10000,
  "read": 10000,
  "rejected": 150,
  "failed": 2300
}

404 Not Found

{
  "message": "Resource not found",
  "details": "Specific validation errors or missing fields"
}

Get Broadcast Recipients

Request

GET https://api.cuedesk.com/broadcasts/{uuid}/recipients?limit=10&offset=0
Authorization: Bearer <token>
Content-Type: application/json

Request Parameters

limit - Limit for pagination (default 50)
offset - Offset for pagination (default 1)
updated - last updated timestamp for recipient message (optional)

Responses

200 OK

{
  "uuid": "d3b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "recipients": [
    {
      "identifier": "325435243",
      "status": "delivered",
      "delivered_at": "2024-06-15T10:00:00Z"
    },
    {
      "identifier": "6563546436",
      "status": "rejected",
      "error": "Invalid template or parameters"
    },
    {
      "identifier": "6563546477",
      "status": "undeliverable",
      "error": "Message validity expired"
    }
  ],
  "pagination": {
    "offset": 1,
    "limit": 50,
    "total": 20000
  }
}

404 Not Found

{
  "message": "Broadcast or recipients not found",
  "details": "Specific validation errors or missing fields"
}

Get Message Statuses - batch

Request

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

Body Parameters

filters - Query filters for the batch request (at least 1 is required)
- broadcastUuid - (optional) UUID of the broadcast to filter by
- clientReferences - (optional) Array of client reference IDs to filter by (up to 1000 references)
- updatedSince - (optional) ISO 8601 timestamp to filter recipients updated after this time
limit - Maximum number of recipients to return per request (required, max: 1000)
offset - Number of recipients to skip (required, used for pagination)

Example

{
  "filters": {
    "broadcastUuid": "d3b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
    "clientReferences": ["ref1", "ref2", "...", "ref100"],
    "updatedSince": "2024-09-15T10:03:00Z"
  },
  "limit": 20,
  "offset": 0
}

Response

200 OK

{
  "recipients": [
    {
      "uuid": "r1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
      "identifier": "1234567890",
      "status": "delivered",
      "delivered_at": "2024-06-15T10:00:00Z",
      "error": null,
      "client_reference": "order-123",
      "broadcast_uuid": "d3b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b"
    }
  ],
  "pagination": {
    "offset": 1,
    "limit": 50,
    "total": 20000
  }
}

Response Fields

recipients - Array of recipient objects
- uuid - Unique recipient ID
- identifier - Recipient phone number
- status - Delivery status (submitted, delivered, read, rejected)
- delivered_at - Timestamp of delivery
- error - Error message if failed
- client_reference - Client-provided reference ID
- broadcast_uuid - Associated broadcast ID
- updated_at - Last update timestamp
metadata - metadata from the request
- pagination - Pagination info

404 Not Found

{
  "message": "Broadcast or recipients not found",
  "details": "Specific validation errors or missing fields"
}

400 Not Found

{
  "message": "error message",
  "details": "Specific validation errors or missing fields"
}

Broadcast API - V1

Create a Broadcast​

Request​

Responses​

202 Accepted​

400 Bad Request​

404 Not Found​

Carousel Broadcasts​

Request​

Broadcast-level card parameters​

Per-recipient card parameters​

Validate a Broadcast payload​

Request​

Responses​

200 OK​

400 Bad Request​

404 Not Found​

Cancel Broadcast​

Request​

Responses​

200 OK​

400 Bad Request​

404 Not Found​

Get Broadcast Details​

Request​

Responses​

200 OK​

404 Not Found​

Get Broadcast Recipients​

Request​

Request Parameters​

Responses​

200 OK​

404 Not Found​

Get Message Statuses - batch​

Request​

Body Parameters​

Example​

Response​

200 OK​

Response Fields​

404 Not Found​

400 Not Found​

Create a Broadcast

Request

Responses

202 Accepted

400 Bad Request

404 Not Found

Carousel Broadcasts

Request

Broadcast-level card parameters

Per-recipient card parameters

Validate a Broadcast payload

Request

Responses

200 OK

400 Bad Request

404 Not Found

Cancel Broadcast

Request

Responses

200 OK

400 Bad Request

404 Not Found

Get Broadcast Details

Request

Responses

200 OK

404 Not Found

Get Broadcast Recipients

Request

Request Parameters

Responses

200 OK

404 Not Found

Get Message Statuses - batch

Request

Body Parameters

Example

Response

200 OK

Response Fields

404 Not Found

400 Not Found