Deprecations

Bird markiert drei verschiedene Dinge als deprecated, und sie verhalten sich unterschiedlich. Ein Request-Feld wird umbenannt, und der alte Name funktioniert weiterhin neben dem neuen. Ein Query-Parameter wird durch einen besseren Filter abgelöst und funktioniert unverändert weiter. Eine Request-Body-Struktur wird durch eine neue Struktur abgelöst, und die alte Struktur wird weiterhin akzeptiert. In jedem Fall enthält die Antwort auf einen Request, der eines davon verwendet, einen Deprecation-Response-Header, der Sie darauf hinweist.

Der Header

Eine Antwort auf einen Request, der ein veraltetes Feld, einen veralteten Parameter oder eine veraltete Body-Struktur enthielt, umfasst:

Header	Wert
Deprecation	Das Datum, an dem die Deprecation angekündigt wurde, zum Beispiel @1786579200
Link	<https://bird.com/docs/api/deprecations>; rel="deprecation"

Der Deprecation-Wert hält fest, wann der alte Name deprecated wurde, gemäß RFC 9745. Er kündigt kein Entfernungsdatum an.

Antworten auf Requests, die nur aktuelle Namen verwenden, enthalten keinen der beiden Header. Das Vorhandensein des Headers ist also das Signal: Wenn Sie ihn nie sehen, ist nichts, was Sie senden, deprecated.

Kein Entfernungsdatum

Bird sendet keinen Sunset-Header, weil noch kein Entfernungsdatum feststeht. Ein abgelöster Name wird erst entfernt, wenn er nicht mehr verwendet wird. Bird kontaktiert betroffene Kunden vor der Entfernung.

Behandeln Sie den Deprecation-Header als Hinweis, in Ihrem eigenen Tempo zu migrieren. Er startet keinen Countdown zur Entfernung.

Ein umbenanntes Request-Feld

Ein abgelöster Feldname verhält sich genau wie zuvor:

Er wird weiterhin bei Requests akzeptiert und schreibt weiterhin denselben Wert.
Er wird weiterhin in Antworten zurückgegeben, neben dem Namen, der ihn ersetzt hat.
Der aktuelle Name hat Vorrang, wenn Sie beide senden. So können Sie eine Aufrufstelle nach der anderen migrieren, ohne dass der alte Name den neuen überschreibt.

Umbenannte Feldnamen sind in dieser Referenz nicht aufgeführt, und die offiziellen SDKs stellen nur die aktuellen Namen bereit. Ein Upgrade Ihres SDK verschiebt Requests daher auf den aktuellen Feldnamen.

Ein veralteter Query-Parameter

Ein Query-Parameter gilt als deprecated, wenn ein besserer Filter ihn ersetzt. Er unterscheidet sich in drei wichtigen Punkten von einem umbenannten Feld:

Er bleibt überall veröffentlicht. Ihn aus der Referenz und den SDKs zu entfernen, würde Aufrufer stören, die ihn bereits senden. Daher behält er seine Zeile in dieser Referenz, sein Feld auf jedem SDK, sein Flag auf dem CLI und seinen Eintrag im MCP-Tool-Schema. Ein Upgrade Ihres SDK migriert Sie nicht.
Es gibt keine Antwortseite. Ein Query-Parameter erscheint immer nur im Request, daher ändert sich nichts im Response-Body und es gibt keinen neuen Namen zum Zurücklesen.
Der Ersatz ist nicht immer ein einzelner Parameter. Ein Filter wird manchmal durch ein Paar abgelöst. Daher nennt die Beschreibung des Parameters, was Sie stattdessen verwenden sollen, statt auf einen einzelnen Nachfolger zu verweisen.

Da ein Upgrade Sie nicht migriert, ist der Deprecation-Header das einzige Signal, das Sie erhalten. Prüfen Sie die Beschreibung des Parameters in dieser Referenz: Eine veraltete beginnt mit Deprecated: und nennt den Ersatz.

Eine abgelöste Request-Body-Struktur

Die Batch-Send-Endpunkte POST /v1/sms/batches und POST /v1/email/batches nahmen den Batch früher als nacktes JSON-Array auf oberster Ebene entgegen. Jetzt erwarten sie ein Objekt, dessen messages-Array dieselben Einträge enthält – die Struktur, die diese Referenz dokumentiert. Ein Request, dessen Body noch das nackte Array ist, funktioniert weiterhin wie zuvor und erhält den Deprecation-Header zurück. Die offiziellen SDKs senden das messages-Objekt. Ein Upgrade Ihres SDK verschiebt Ihre Requests daher auf die aktuelle Struktur.

Migration

Achten Sie auf den Deprecation-Header in Ihren Antworten.
Ermitteln Sie den Request, der ihn ausgelöst hat, und prüfen Sie in dieser Referenz die Operation, um die aktuellen Namen und die Request-Struktur zu sehen.
Wechseln Sie zum aktuellen Namen oder zur aktuellen Struktur. Senden Sie danach nur noch die aktuelle Form.

Aktuelle Deprecations

Operation	Deprecated	Stattdessen verwenden
WhatsApp: Nachrichten auflisten	phone_number-Query-Parameter	to oder from
SMS und E-Mail: einen Nachrichten-Batch erstellen	Bare-Array-Request-Body	ein Objekt mit messages

Keine Feldumbenennung ist deprecated. Die Telefonnummer eines Kontakts ist phone_number und die E-Mail-Adresse eines Verifizierungsempfängers ist email innerhalb von to; jede andere Schreibweise wird als Validierungsfehler abgelehnt, bei jeder Operation, die sie entgegennimmt.

to und from in der WhatsApp-Nachrichtenliste treffen jeweils ein Ende der Nachricht, und beide akzeptieren eine Telefonnummer oder eine geschäftsbereichsbezogene User-ID. phone_number traf den Kontakt in beiden Richtungen. Eine Suche, die die Richtung nicht berücksichtigt, benötigt daher beide Filter, je einen pro Request.

Verwandte Ressourcen