Broadcasts API

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"]
  },
  "version": 1,
  "client_unique_identifier": "abe120b4-048c-4d00-9c1a-0b01d34c583c",
  "recipients": [
    {
      "identifier": "447592850122",
      "client_reference": "541d2b80-7569-4774-8798-f89c3378bbfa",
      "parameters": {
        "body": {
          "Name": "Alex",
          "Place": "City Centre",
          "Time": "18h00"
        }
      }
    },
    {
      "identifier": "27827134468",
      "client_reference": "541d2b80-7569-4774-8798-f89c3378bbfa",
      "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)
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)
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) paremetersTemplate parameters for this contact. Optional, depending on the template requirements. body: Body parameters for the template message body

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"
}

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)
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) paremetersTemplate parameters for this contact. Optional, depending on the template requirements. body: Body parameters for the template message body

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"
}