Skip to content
Broadcasts

List broadcast recipients

GET
/broadcasts/{id}/recipients
 
const url = 'https://api.kirimdev.com/v1/broadcasts/bcst_01HXYZABCDEFGHJKMNPQRSTVWX/recipients?status=pending&limit=25&cursor=eyJpZCI6IjAxSFhZWkFCQ0RFRkdISktNTlBRUlNUVldYIiwidHMiOiIyMDI2LTA5LTEwVDA5OjAwOjAwLjAwMFoifQ';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

List the recipients of one broadcast in send order, with each recipient’s delivery status, Meta wamid, timestamps and failure reason. Filter by status (for example failed) to export only the rows you need.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required

Public Kirimdev broadcast ID.

string
/^bcst_[0-9A-HJKMNP-TV-Z]{26}$/
Example 
bcst_01HXYZABCDEFGHJKMNPQRSTVWX

Public Kirimdev broadcast ID.

Query Parameters

Section titled “Query Parameters ”
status

Filter by the recipient’s current delivery status.

string
Allowed values: pending queued sent delivered read failed
Example 
failed

Filter by the recipient’s current delivery status.

limit

Number of items to return. Defaults to 25; minimum 1 and maximum 100.

string
default: 25 /^\d+$/
Example 
25

Number of items to return. Defaults to 25; minimum 1 and maximum 100.

cursor

Opaque continuation token from the previous response’s next_cursor. Pass it unchanged and keep all other filters the same.

string
>= 1 characters
Example 
eyJpZCI6IjAxSFhZWkFCQ0RFRkdISktNTlBRUlNUVldYIiwidHMiOiIyMDI2LTA5LTEwVDA5OjAwOjAwLjAwMFoifQ

Opaque continuation token from the previous response’s next_cursor. Pass it unchanged and keep all other filters the same.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Recipient list

Media type application/json
object
data
required

Items in this page, ordered as documented by the operation.

Array<object>
object
object
required
string
Allowed values: broadcast_recipient
contact_id
required
string
contact_name
required
string | null
phone_number
required

E.164 with leading +. null for a BSUID-only recipient.

string | null
bsuid
required
string | null
status
required
string
Allowed values: pending queued sent delivered read failed
wamid
required

Meta message id. Matches message.status webhook events. null until Meta accepts the send.

string | null
error
required
object
code
required
string | null
message
required
string | null
provider_code
required
number | null
sent_at
required
string | null format: date-time
delivered_at
required
string | null format: date-time
read_at
required
string | null format: date-time
failed_at
required
string | null format: date-time
created_at
required
string format: date-time
has_more
required

Whether another page is available.

boolean
next_cursor
required

Pass this value unchanged as cursor to fetch the next page. null marks the final page.

string | null
request_id
required

Unique request identifier to include when contacting support.

string
Example 
{
  "data": [
    {
      "object": "broadcast_recipient",
      "contact_id": "ctc_01HXYZABCDEFGHJKMNPQRSTVWX",
      "phone_number": "+628123456789",
      "status": "pending",
      "wamid": "wamid.HBgN...",
      "error": {
        "code": "billing_issue",
        "provider_code": 131042
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}

400

Section titled “400 ”

Validation failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

A field value is invalid.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_field_value",
    "message": "A field value is invalid.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

401

Section titled “401 ”

Authentication failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The provided API key is invalid.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

404

Section titled “404 ”

Resource not found

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Resource not found.

{
  "error": {
    "type": "not_found",
    "code": "resource_not_found",
    "message": "Resource not found.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

429

Section titled “429 ”

Rate limit exceeded

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Rate limit exceeded.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

500

Section titled “500 ”

Internal server error

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

An unexpected error occurred.

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}