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);

result = client.amb.suppressions.list(business_id='abz_01krdgeqcxet5s7t44vh8rt9mg', limit=2)
print(result)

for item, err := range client.Amb.Suppressions.List(ctx, bird.AmbSuppressionsListParams{BusinessID: "abz_01krdgeqcxet5s7t44vh8rt9mg", Limit: 2}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(item)
}

foreach ($bird->amb->suppressions->list(['business_id' => 'abz_01krdgeqcxet5s7t44vh8rt9mg', 'limit' => '2']) as $item) {
    var_dump($item);
}

bird amb suppressions list

curl -X GET "https://us1.platform.bird.com/v1/amb/suppressions" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "handle=+15551234567" \
  --url-query "limit=25"

Antwort200

{
  "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.

Abfrageparameter

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.

Antwort-Payload

data

array of object

erforderlich

Active suppression episodes for the workspace, most recently effective first. Episodes that have ended are left out; fetch one by ID to read it.

Untergeordnete Attribute anzeigen

data.created_at

string

erforderlich

data.updated_at

string

erforderlich

data.id

string

erforderlich

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

erforderlich

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

erforderlich

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

erforderlich

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

erforderlich

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

erforderlich

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

erforderlich

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

erforderlich

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor

nullable string

erforderlich

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor

nullable string

erforderlich

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.

List Apple Messages for Business suppressions

Verwandte Ressourcen