Sign inGet Started
Mulai sekarang
Panduan
Referensi API
SDK
CLI
Basis Pengetahuan
Changelog

Create an Apple Messages for Business suppression

POST
/v1/amb/suppressions
const result = await bird.amb.suppressions.create({
  handle: "opaque-customer",
  handle_type: "opaque_user_id",
  business_id: null,
});
console.log(result);
Respons200
{
  "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
}
Manually opens a suppression episode for a handle, blocking every outbound path to it: operator and automated replies, API sends, typing indicators, and invitations. Set business_id to block the handle for one brand only, or omit it to block the handle for every brand in the workspace. If the handle already has an active episode with reason manual, the API returns 200 with the existing episode instead of creating a second one.
Payload Permintaan
business_id
nullable string
Suppress the handle for this brand only. Omit or send null to block it for every brand in the workspace.
handle
string
wajib
The phone number or opaque identifier to suppress. For a phone number, supply canonical E.164 with a leading plus sign.
handle_type
string
wajib
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
Payload Respons
created_at
string
wajib
updated_at
string
wajib
id
string
wajib
Unique identifier for the suppression episode.
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.
handle
string
wajib
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.
handle_type
string
wajib
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
reason
string
wajib
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
origin
string
wajib
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
applies_to
string
wajib
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
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.
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.
effective_at
string
wajib
When this episode started blocking outbound messages.
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.
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
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.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integrationPanduan implementasiSend your first email
Dapatkan ringkasan implementasi