Sign inGet Started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

List Apple Messages for Business suppressions

GET
/v1/amb/suppressions
const result = await bird.amb.suppressions.list({
  business_id: "abz_01krdgeqcxet5s7t44vh8rt9mg",
  limit: 2,
});
console.log(result);
Reactie200
{
  "data": [
    {
      "created_at": "2026-05-20T09:14:52Z",
      "updated_at": "2026-05-25T16:42:01Z",
      "id": "asp_01krdgeqcxet5s7t44vh8rt9mg",
      "business_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
      "handle": "+15551234567",
      "handle_type": "opaque_user_id",
      "reason": "manual",
      "origin": "user",
      "applies_to": "all",
      "source_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
      "source_end_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
      "effective_at": "2026-08-12T09:00:00Z",
      "ended_at": null,
      "ended_reason": null,
      "ended_effective_at": null
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
Returns a paginated list of the workspace's active Apple Messages for Business suppressions: customers who have opted out of one brand, or of the whole workspace. Episodes that have ended are left out; fetch one by ID to read it. Filter by business_id to see one brand's suppressions, including the workspace-wide ones that block it too.
Queryparameters
business_id
string
Keep only suppressions for this brand, including the workspace-wide ones that block it too. Omit to see suppressions for every brand in the workspace.
handle
string
Prefix filter on the suppressed phone number or opaque identifier (case-insensitive). A complete value returns only that handle; a partial value returns every match.
handle_type
string
Keep only suppressions of this kind.
Possible values: phone_number, opaque_user_id
reason
string
Keep only suppressions with this reason.
Possible values (may grow over time): manual, opted_out
limit
integer
Maximum number of items to return per page.
starting_after
string
Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_before
string
Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.
Response Payload
data
array of object
verplicht
Active suppression episodes for the workspace, most recently effective first. Episodes that have ended are left out; fetch one by ID to read it.
Onderliggende attributen tonen
data.created_at
string
verplicht
data.updated_at
string
verplicht
data.id
string
verplicht
Unique identifier for the suppression episode.
data.business_id
nullable string
The brand this episode applies to, or null when it covers every brand in the workspace. Apple requires that a brand not message someone who opted out of it, so an episode scoped to one brand does not suppress a sibling brand in the same workspace.
data.handle
string
verplicht
The suppressed phone number or opaque identifier. handle_type says which. For a phone number this is canonical E.164 with a leading plus sign.
data.handle_type
string
verplicht
What kind of value handle holds.
  • phone_number means handle is the customer's phone number. Apple's CloseSession event carries a phone number rather than an opaque identifier, so a suppression opened by a close on a conversation identified by phone number takes this kind.
  • opaque_user_id means handle is the opaque identifier Apple assigns to the customer's conversation with the business, stable across a close and a later re-initiation.
Possible values: phone_number, opaque_user_id
data.reason
string
verplicht
Why the handle is suppressed. manual means it was added directly through this API or the dashboard. opted_out covers every case where Apple or the customer signaled they should not be contacted: a close, a permanent delivery failure, a declined invitation, or a stop keyword. This list grows over time, so treat an unknown value as informational rather than rejecting the record.
Possible values (may grow over time): manual, opted_out
data.origin
string
verplicht
How this episode came to exist.
  • user means a dashboard user added it directly.
  • api_key means an API caller added it directly.
  • close_session means the customer sent Apple's close event, ending the conversation.
  • gone means a send to the handle returned Apple's permanent-failure response, which Bird treats as the same signal as a close.
  • invitation_declined means the customer declined an invitation. No operation writes this value yet; it starts once invitations ship.
  • keyword means the customer sent a stop keyword. No operation writes this value yet; it starts once keyword automation ships.
Possible values: user, api_key, close_session, gone, invitation_declined, keyword
data.applies_to
string
verplicht
What this episode blocks. all blocks every outbound path: operator and automated replies, API sends, typing indicators, and invitations. invitations blocks only a new invitation to the handle, leaving replies in a conversation the customer opens directly unaffected; no operation writes this value yet, since invitations are a future feature. This list grows over time, so treat an unknown value as blocking.
Possible values (may grow over time): all, invitations
data.source_message_id
nullable string
ID of what opened this episode. A permanent delivery failure on send names the message that failed, an amb_ id. A close names the conversation event Bird recorded for it instead, an aev_ id, because a close carries no message of its own. Null for an episode opened directly through this API or by a phone-addressed close that has no conversation event.
data.source_end_message_id
nullable string
ID of the inbound message that ended this episode by re-initiating the conversation. Null while the episode is still in force, and null for an episode ended through this API instead.
data.effective_at
string
verplicht
When this episode started blocking outbound messages.
data.ended_at
nullable string
When this episode stopped applying. Null while it is still blocking outbound messages, which is the case for every episode the list returns.
data.ended_reason
nullable string
What ended it. reinitiated means the same customer started the conversation again: this ends an episode opened by close_session or gone automatically, with no API call, and does not apply to one opened by invitation_declined, which needs an explicit re-subscription instead. user and api_key mean this API ended it directly, which works for an episode of any origin. Null while the episode is still in force.
Possible values (may grow over time): user, api_key, reinitiated
data.ended_effective_at
nullable string
When the ended state took effect, which can differ from ended_at when the record of an end arrives later than the event that caused it.
next_cursor
nullable string
verplicht
Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.
prev_cursor
nullable string
verplicht
Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.
refresh_cursor
nullable string
verplicht
Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Begrijp het conceptShould I use a Bird SDK or call the API directly?Volg het leerpadBuild your first integrationImplementatiegidsSend your first email
Ontvang een implementatieoverzicht