Dieser Artikel behandelt die Fehler, die bei der Verwendung der WhatsApp Public API auftreten können, wie Qualitätsbewertungen und Nachrichten-Stufen Ihre Sendefähigkeit beeinflussen und was Sie selbst beheben können im Vergleich zu dem, was Maßnahmen von Meta oder dem Aircall Support erfordert.
Fehlerreferenz
| Fehler | Bedeutung | Maßnahme |
|---|---|---|
| 403 | Der Account ist auf Essentials, hat kein aktives WhatsApp-Add-on oder die Funktion ist nicht aktiviert | Bestätigen Sie Abonnement- und Add-on-Status im Aircall Dashboard. Kontaktieren Sie den Aircall Support, um zu prüfen, ob die Funktion in Ihrem Abonnement verfügbar ist. |
| 400 — line not configured | Die Leitung wurde nicht für die Verwendung mit der Public API registriert | Rufen Sie zuerst POST /v1/numbers/{id}/messages/configuration auf. |
| 400 — template not approved | Die gesendete Vorlage hat in Meta nicht den Status APPROVED | Prüfen Sie den Vorlagenstatus im Meta Business Manager. Dies kann nicht von Aircall behoben werden. |
| 63016 — 24-hour window expired | Das Senden gibt eine 200-Antwort zurück, aber Ihr Webhook empfängt einen Callback mit einem Fehler, wenn Freitext außerhalb des Konversationsfensters gesendet wird | Verwenden Sie eine genehmigte Vorlage, um eine Konversation mit Ihrem Kunden erneut zu initiieren. Siehe den Abschnitt zum 24-Stunden-Fenster im Artikel Erste Schritte mit der Whatsapp Public API . |
| 400 — WABA not configured | Für die WhatsApp-Leitung ist kein WABA (WhatsApp Business Account) eingerichtet | Kontaktieren Sie den Aircall Support. Dies ist ein Problem mit der Leitungs-Konfiguration. |
| 400 — line OFFLINE or BLOCKED | Die Leitung ist nicht in einem aktiven Sendestatus | Prüfen Sie den Endpunkt für den Leitungsstatus. Wenn BLOCKED, kontaktieren Sie den Aircall Support. |
| 429 | Limit der Nachrichten-Stufe überschritten: tägliche Konversationsobergrenze erreicht | Von Meta auferlegtes Limit. Wird alle 24 Stunden zurückgesetzt. Kann von Aircall nicht überschrieben werden. |
| 131048 | Meta-Spam-Ratenlimit: Sendungen von dieser Rufnummer werden von Meta eingeschränkt | Prüfen Sie Ihre Nachrichtenqualität und kontaktieren Sie den Meta Business Support. Aircall kann dies nicht überschreiben. |
| 131045 | Fehler bei der Registrierung der Rufnummer bei einem externen Anbieter | Kontaktieren Sie den Aircall Support |
| 131000 | Unbekannter Meta-Fehler | Wenn der Fehler weiterhin auftritt, kontaktieren Sie den Aircall Support mit Ihrer Unternehmens-ID, Leitungs-ID, der vollständigen Fehler-Payload und einem Zeitstempel. |
Das 24-Stunden-Konversationsfenster
Das Konversationsfenster von WhatsApp ist eine Regel von Meta, keine Aircall-Einstellung. Es steuert, wann Freitextnachrichten gesendet werden können.
- Ein 24-Stunden-Fenster öffnet sich, wenn ein Kunde Ihrer Rufnummer schreibt oder auf eine Ihrer Nachrichten antwortet.
- Innerhalb dieses Fensters können Sie Freitext senden.
- Sobald das Fenster geschlossen ist, können Sie nur noch eine genehmigte Vorlage senden, um die Konversation erneut zu starten.
ACHTUNG: Der Versuch, Freitext außerhalb eines offenen Fensters zu senden, gibt einen Fehler an Ihren Webhook zurück. Die Lösung besteht immer darin, zuerst eine genehmigte Vorlage zu senden. Aircall kann das Fenster nicht überschreiben oder verlängern.
Qualitätsbewertung
Meta weist jeder WhatsApp-Leitung eine Qualitätsbewertung zu, basierend darauf, wie Empfänger auf Nachrichten von dieser Rufnummer reagieren. Wenn Empfänger Ihre Rufnummer häufig blockieren oder melden, verschlechtert sich die Bewertung.
- GREEN: Leitung in gutem Zustand, keine Sendeeinschränkungen.
- YELLOW: Die Qualität verschlechtert sich, oft weil Kunden Ihre Nachrichten als Spam melden oder Ihre Rufnummer blockieren. Prüfen Sie die Qualität der Vorlagen und erwägen Sie, das Sendevolumen zu reduzieren.
- RED: Meta hat diese Leitung eingeschränkt. Sendungen können fehlschlagen. Kontaktieren Sie den Meta Business Support.
ACHTUNG: Qualitätsbewertungen werden von Meta festgelegt und kontrolliert. Aircall kann sie nicht ändern. Eine Verbesserung Ihrer Bewertung erfordert bessere Vorlagen, sauberere Kontaktlisten und bestätigte Opt-ins der Empfänger.
Nachrichten-Stufen
Meta begrenzt die Anzahl der vom Unternehmen initiierten Konversationen, die eine Leitung pro 24-Stunden-Zeitraum starten kann. Das ist die Nachrichten-Stufe. Die Stufen erhöhen sich automatisch, wenn Meta mehr Vertrauen in die Qualität einer Rufnummer und ihre Sendemuster gewinnt. Es gibt keinen manuellen Prozess, um eine Erhöhung der Stufe zu beantragen.
| Stufe | Konversationen pro 24 Stunden | Typischer Account-Typ |
|---|---|---|
| TIER_250 | 250 | Neue oder nicht verifizierte Leitungen |
| TIER_1K | 1,000 | Standardmäßig verifizierte Unternehmen |
| TIER_10K | 10,000 | Etablierte Sender mit hoher Qualität |
| TIER_100K | 100,000 | Verifizierte Unternehmen mit hohem Volumen |
HINWEIS: Wenn Ihre Integration einen 429-Fehler zurückgibt, wurde das tägliche Stufenlimit erreicht. Das Limit wird alle 24 Stunden zurückgesetzt. Bauen Sie für diesen Fall eine Wiederholungslogik in Ihre Integration ein.
Was Sie kontrollieren können und was nicht
Einige Einschränkungen werden von Meta festgelegt und können weder von Aircall noch von Ihnen geändert werden.
Folgendes kann von niemandem bei Aircall überschrieben werden:
- Qualitätsbewertungen
- Limits der Nachrichten-Stufen
- Die Entsperrung einer Rufnummer, die von Meta eingeschränkt wurde
- Die Genehmigung oder Ablehnung von WhatsApp-Nachrichtenvorlagen
- Das 24-Stunden-Konversationsfenster
Kontaktieren Sie den Aircall Support für:
- Prüfung oder Aktivierung des Funktionsstatus
- Fehler zu WABA nicht konfiguriert (400)
- Leitungen mit Status OFFLINE oder BLOCKED
- Fehler bei der Registrierung von Rufnummern (131045)
- Anhaltende unbekannte Fehler (131000): Geben Sie Ihre Unternehmens-ID, Leitungs-ID, vollständige Fehler-Payload und den Zeitstempel an
Kontaktieren Sie direkt den Meta Business Support für:
- Spam-Ratenbeschränkungen (131048)
- Verschlechterung der Qualitätsbewertung
- Von Meta vollständig blockierte Leitungen
FAQs
Meine API-Aufrufe geben einen 403 zurück, obwohl wir ein WhatsApp-Add-on haben. Was ist falsch?
Ein 403 kann auch bedeuten, dass die Funktion für Ihren Account noch nicht aktiviert ist oder dass Ihr Abonnement Essentials ist. Kontaktieren Sie den Aircall Support, um zu bestätigen, dass alle Voraussetzungen erfüllt sind: Pro-Abonnement oder höher, aktives WhatsApp-Add-on und die Leitung ist registriert.
Kann ich einem Kunden eine Nachricht senden, der uns noch nie zuerst geschrieben hat?
Ja, verwenden Sie eine genehmigte Vorlage. Genehmigte Vorlagen können außerhalb des 24-Stunden-Fensters gesendet werden, um den Kontakt zu initiieren. Freitextnachrichten erfordern ein offenes Konversationsfenster, das heißt, der Kunde muss Ihnen geschrieben oder innerhalb der letzten 24 Stunden geantwortet haben.
Warum zeigt meine Leitung eine Qualitätsbewertung YELLOW oder RED an?
Meta verschlechtert Qualitätsbewertungen, wenn Empfänger Nachrichten von Ihrer Rufnummer blockieren oder melden. Dies ist typischerweise die Folge von unaufgeforderten Nachrichten, Vorlagen niedriger Qualität oder dem Anschreiben von Kontakten, die kein Opt-in erteilt haben. Aircall kann diese Bewertung nicht ändern. Verbessern Sie Ihre Messaging-Praktiken und geben Sie der Bewertung Zeit, sich auf natürliche Weise zu erholen.
Wie schnell werden Limits der Nachrichten-Stufen zurückgesetzt?
Alle 24 Stunden ab dem Zeitpunkt, an dem das Limit erreicht wurde. Wenn Sie einen 429-Fehler erhalten, warten Sie 24 Stunden, bevor Sie es erneut versuchen. Die Stufen erhöhen sich im Laufe der Zeit automatisch, wenn Meta mehr Vertrauen in Ihre Sendequalität gewinnt.
Wir möchten, dass HubSpot oder Salesforce WhatsApp-Nachrichten automatisch senden. Wo beginnen wir?
Beginnen Sie mit dem unten verlinkten Artikel zu den ersten Schritten. Sobald Ihre Leitung registriert ist, kann Ihr CRM- oder RevOps-Team Workflows erstellen, die POST /v1/messages/whatsapp/send aufrufen, wenn sich Deal-Phasen ändern, Verträge bereit sind oder andere auslösende Ereignisse eintreten.