Einer Messaging-Kampagne eine Nummer zuweisen

Eine Sendenummer einer Kampagne zuweisen

Verwenden Sie diesen Vorgang, nachdem Ihre Messaging-Marke und Ihre Produktionskampagne registriert sind und die Kampagne aktiv ist. Er verknüpft eine SMS-fähige Nummer Ihres Kontos mit der Kampagne. Er erstellt keine Marke, erstellt oder genehmigt keine Kampagne, kauft keine Nummer und sendet keine Nachricht.

Das aktuelle Portal verwendet diese Route, wenn es einer Nummer eine Kampagne zuweist. Die öffentliche API akzeptiert eine Kampagnenkennung; sie leitet die Marke aus der kontoeigenen Kampagne ab, statt eine separate Markenkennung zu akzeptieren.

Anfrage

Senden Sie einen formularcodierten POST über HTTPS mit Ihrem aktivierten API-Konto und dessen zugelassener Quell-IP-Adresse. Verwenden Sie die tatsächlichen Nummern- und Kampagnenkennungen aus Ihrem Konto. Die Nummer in diesem Beispiel ist fiktiv.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=add' \
  --data-urlencode "campaign=$CAMPAIGN_ID" \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Parameter der Kampagnenzuweisung
Parameter	Erforderlich	Bedeutung
action	Ja	Verwenden Sie add, um eine Kampagnenverknüpfung der Nummer zuzuweisen, oder delete, um die aktuelle Kampagnenverknüpfung der Nummer zu entfernen. Groß-/Kleinschreibung und umgebende Leerzeichen werden normalisiert.
campaign	Für add	Die campaignId einer Kampagne im Status ACTIVE, die dem authentifizierten Konto gehört. Ihre Marke muss ebenfalls zum Konto gehören. Eine ausdrücklich als Sandbox gekennzeichnete Kampagne kann keinen Live-Sendenummern zugewiesen werden. Lassen Sie diesen Parameter bei delete weg; die Entfernung verwendet die bestehende Verknüpfung der Nummer.
number	Ja	Die eigene, aktive, nicht annullierte, SMS-fähige Sendenummer. Verwenden Sie für eine nordamerikanische Nummer die Landesvorwahl 1, gefolgt von ihren zehn Ziffern, ohne Pluszeichen. Der Handler entfernt alle Zeichen, die keine Ziffern sind, und sucht zusätzlich nach den Entsprechungen mit Plus-Präfix und mit zehn Ziffern. Diese Normalisierung ist keine allgemeine Gültigkeitsprüfung von Telefonnummern.

Der Vorgang ändert eine Nummer. Er hat keine Paginierung, keinen Batch-Parameter und keine Trockenlauf-Option. Verwenden Sie keinen Endpunkt zur Kampagnenerstellung, nur um eine Nummer an eine bestehende Kampagne anzuhängen.

Die aktuelle Verknüpfung entfernen

Verwenden Sie action=delete mit der eigenen Nummer. Dies entfernt ihre Verknüpfung mit der Sendekampagne und leert die gespeicherten Marken-/Kampagnenfelder dieser Nummer. Es löscht weder die Kampagne noch die Marke, gibt die Telefonnummer nicht frei, kündigt den Dienst der Nummer nicht und stoppt nicht die wiederkehrende Abrechnung der Kampagne.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=delete' \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Antwort und Überprüfung

Dieses fiktive Beispiel zeigt den üblichen API-Antwortumschlag und ausgewählte Ergebnisfelder. Die zurückgegebene Nummer behält das in Ihrem Konto gespeicherte Format bei. brandId und campaignId sind nach einer erfolgreichen Entfernung leere Zeichenketten.

{
  "status": {"code": 200, "msg": "Campaign assignment updated."},
  "response": {
    "number": "+12025550123",
    "brandId": "BRAND_FROM_ACCOUNT",
    "campaignId": "CAMPAIGN_FROM_ACCOUNT",
    "providerStatus": 200
  }
}

providerStatus ist der HTTP-Status des Messaging-Partners. Der Handler akzeptiert eine 2xx-Transportantwort und aktualisiert anschließend den lokalen Nummerndatensatz; er wertet den Antworttext des Partners nicht auf ein separates Abnahmeergebnis auf Geschäftsebene aus. Eine Erfolgsantwort ist daher kein Beweis dafür, dass die Messaging-Registrierung abgeschlossen ist oder dass die Zustellung gelingen wird. Prüfen Sie den Kampagnenstatus der Nummer im Portal, bevor Sie Produktionsverkehr senden.

Betrachten Sie eine lokale Verknüpfung allein nicht als Zustellfreigabe. Kampagnen- und Markengenehmigung, Nummernbereitstellung, Kontoberechtigungen, Inhaltsregeln und übliche Messaging-Limits gelten weiterhin.

Fehler und Teilergebnisse

401: Dem Handler steht kein authentifiziertes Konto zur Verfügung.
400: action oder number fehlt oder ist ungültig, oder eine add-Anfrage enthält keine Kampagnenkennung.
404: Die Nummer ist keine eigene, aktive, nicht annullierte SMS-Nummer.
409: Die Kampagne ist für das Konto nicht verfügbar, ist nicht ACTIVE, ist ausdrücklich Sandbox, oder ihre Marke ist für das Konto nicht verfügbar.
503: Die Messaging-Integration ist nicht verfügbar. Wenden Sie sich an den Support, statt Kontozugangsdaten zu ändern oder Konfigurationswerte zu erfinden.
502: Die Messaging-Anfrage ist fehlgeschlagen, hat das Zeitlimit überschritten oder einen HTTP-Status außerhalb von 2xx zurückgegeben. providerStatus kann zurückgegeben werden. Eine Zeitüberschreitung beweist nicht, dass der Partner keine Änderung vorgenommen hat.
500 mit partial=true: Der Messaging-Partner hat einen erfolgreichen HTTP-Status zurückgegeben, aber die lokale Verknüpfung konnte nicht bestätigt werden. Gleichen Sie die Nummer im Portal ab oder wenden Sie sich an den Support, bevor Sie es erneut versuchen.

Prüfen Sie den API-Statuscode und den Antworttext ebenso wie das HTTP-Ergebnis. Wiederholen Sie eine Anfrage nach einer Zeitüberschreitung oder einem Teilergebnis nicht blind. Dieser Handler hat keinen Idempotenzschlüssel auf Anfrageebene, kein transaktionales Rollback und keine Prüfung des Abschlusses der Kampagnenregistrierung. Eine wiederholte, übereinstimmende lokale Zuweisung kann Erfolg zurückgeben, selbst wenn die Datenbank keine geänderten Zeilen meldet.

Umfang und Auswirkungen

Dieser Vorgang ändert das Routing der Sendenummer und ihre gespeicherte Kampagnen-/Markenverknüpfung. Im geprüften Handler enthält er keine direkte Kontobelastung, keine Kampagnenerstellung, keinen Kauf und keinen Nachrichtenversand. Dies ist kein Preisangebot und kein Versprechen eines kostenlosen Dienstes: Bestehende Gebühren für Nummer, Kampagne und Messaging laufen gemäß Ihren Kontobedingungen weiter.

Im Portal entfernt der Wechsel zu einer anderen Kampagne zuerst die bisherige Verknüpfung und fügt dann die neue hinzu. Das sind getrennte Anfragen. Schlägt die zweite Anfrage fehl, ist die frühere Verknüpfung möglicherweise bereits entfernt. Gehen Sie nicht davon aus, dass die beiden Anfragen gemeinsam zurückgerollt werden.