Przypisywanie numeru do kampanii wiadomości

Przypisywanie numeru nadawczego do kampanii

Użyj tej operacji po zarejestrowaniu marki wiadomości i kampanii produkcyjnej, gdy kampania jest aktywna. Operacja powiązuje jeden numer z obsługą SMS na Twoim koncie z kampanią. Nie tworzy marki, nie tworzy ani nie zatwierdza kampanii, nie kupuje numeru i nie wysyła wiadomości.

Bieżący portal używa tej ścieżki podczas przypisywania kampanii do numeru. Publiczne API przyjmuje identyfikator kampanii; markę wyprowadza z kampanii należącej do konta, zamiast przyjmować osobny identyfikator marki.

Żądanie

Wyślij żądanie POST zakodowane jako formularz przez HTTPS, używając włączonego konta API i jego dozwolonego źródłowego adresu IP. Użyj rzeczywistych identyfikatorów numeru i kampanii ze swojego konta. Numer w tym przykładzie jest fikcyjny.

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'

Parametry przypisania kampanii
Parametr	Wymagany	Znaczenie
action	Tak	Użyj add, aby przypisać, lub delete, aby usunąć bieżące powiązanie numeru z kampanią. Wielkość liter i otaczające spacje są normalizowane.
campaign	Dla add	campaignId kampanii o statusie ACTIVE należącej do uwierzytelnionego konta. Jej marka również musi należeć do konta. Kampanii wyraźnie oznaczonej jako sandbox nie można przypisać do produkcyjnych numerów nadawczych. Pomiń ten parametr dla delete; usunięcie korzysta z istniejącego powiązania numeru.
number	Tak	Posiadany, aktywny, nieunieważniony numer nadawczy z obsługą SMS. Dla numeru północnoamerykańskiego użyj kodu kraju 1, po którym następuje dziesięć cyfr numeru, bez znaku plus. Procedura obsługi usuwa znaki niebędące cyframi i wyszukuje również odpowiedniki z prefiksem plus oraz dziesięciocyfrowe. Ta normalizacja nie jest ogólną kontrolą poprawności numeru telefonu.

Operacja zmienia jeden numer. Nie ma stronicowania, parametru wsadowego ani opcji próbnego uruchomienia. Nie używaj punktu końcowego tworzenia kampanii jedynie po to, aby dołączyć numer do istniejącej kampanii.

Usuwanie bieżącego powiązania

Użyj action=delete z posiadanym numerem. Usuwa to jego powiązanie z kampanią nadawczą i czyści zapisane pola marki/kampanii dla tego numeru. Nie usuwa kampanii ani marki, nie zwalnia numeru telefonu, nie anuluje usługi numeru ani nie zatrzymuje cyklicznych opłat za kampanię.

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

Odpowiedź i weryfikacja

Ten fikcyjny przykład ilustruje zwykłą kopertę odpowiedzi API i wybrane pola wyniku. Zwracany numer zachowuje format zapisany na Twoim koncie. brandId i campaignId są pustymi ciągami znaków po pomyślnym usunięciu.

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

providerStatus to status HTTP partnera wiadomości. Procedura obsługi akceptuje odpowiedź transportową 2xx, a następnie aktualizuje lokalny rekord numeru; nie interpretuje treści odpowiedzi partnera pod kątem osobnego wyniku akceptacji biznesowej. Odpowiedź o powodzeniu nie jest więc dowodem, że rejestracja wiadomości została zakończona ani że dostarczanie się powiedzie. Przed wysyłaniem ruchu produkcyjnego sprawdź status kampanii numeru w portalu.

Nie traktuj samego lokalnego powiązania jako zatwierdzenia dostarczania. Zatwierdzenie kampanii i marki, udostępnienie numeru, uprawnienia konta, zasady dotyczące treści i zwykłe limity wiadomości nadal obowiązują.

Błędy i wyniki częściowe

401: procedura obsługi nie ma dostępu do żadnego uwierzytelnionego konta.
400: brakuje parametru action lub number albo jest on nieprawidłowy, lub żądanie add nie zawiera identyfikatora kampanii.
404: numer nie jest posiadanym, aktywnym, nieunieważnionym numerem SMS.
409: kampania jest niedostępna dla konta, nie ma statusu ACTIVE, jest wyraźnie oznaczona jako sandbox lub jej marka jest niedostępna dla konta.
503: integracja wiadomości jest niedostępna. Skontaktuj się z pomocą techniczną, zamiast zmieniać poświadczenia konta lub wymyślać wartości konfiguracyjne.
502: żądanie do partnera wiadomości nie powiodło się, przekroczyło limit czasu lub zwróciło status HTTP inny niż 2xx. Może zostać zwrócony providerStatus. Przekroczenie limitu czasu nie dowodzi, że partner nie wprowadził żadnej zmiany.
500 z partial=true: partner wiadomości zwrócił pomyślny status HTTP, ale lokalnego powiązania nie udało się potwierdzić. Przed ponowieniem próby uzgodnij numer w portalu lub skontaktuj się z pomocą techniczną.

Sprawdź kod statusu API i treść odpowiedzi, a także wynik HTTP. Nie ponawiaj bezrefleksyjnie żądania po przekroczeniu limitu czasu ani po wyniku częściowym. Ta procedura obsługi nie ma klucza idempotentności na poziomie żądania, transakcyjnego wycofania zmian ani kontroli zakończenia rejestracji kampanii. Powtórzone identyczne lokalne przypisanie może zwrócić powodzenie nawet wtedy, gdy baza danych nie zgłasza żadnych zmienionych wierszy.

Zakres i skutki

Ta operacja zmienia routing numeru nadawczego i jego zapisane powiązanie z kampanią/marką. W przejrzanej procedurze obsługi nie zawiera bezpośredniego obciążenia konta, tworzenia kampanii, zakupu ani wysyłki wiadomości. Nie jest to wycena ani obietnica bezpłatnej usługi: istniejące opłaty za numer, kampanię i wiadomości nadal obowiązują zgodnie z warunkami Twojego konta.

W portalu zmiana na inną kampanię najpierw usuwa poprzednie powiązanie, a następnie dodaje nowe. Są to osobne żądania. Jeśli drugie żądanie się nie powiedzie, wcześniejsze powiązanie może być już usunięte. Nie zakładaj, że oba żądania są wycofywane razem.