Przed wysłaniem
Wyślij SMS lub obsługiwany MMS z numeru nadawczego skonfigurowanego dla Twojego konta. Jest to operacja produkcyjna, która może spowodować kontakt z odbiorcami i naliczenie opłat. Wysyłaj wyłącznie do odbiorców, z którymi masz prawo się kontaktować, i tylko w ramach zatwierdzonego ruchu; poniższe przykładowe numery i oznaczenie referencyjne są fikcyjne.
Twoje konto wymaga zgody na wysyłanie wiadomości oraz odpowiednich uprawnień dotyczących nadawcy, kraju i ruchu. Dane uwierzytelniające użytkowników typu Personal/Consumer używane bezpośrednio nie uprawniają do korzystania z tego API. Zatwierdzone, dedykowane dane uwierzytelniające API podlegają odrębnej procedurze kwalifikacji; nadawcy mobilni P2P mogą wymagać dodatkowych uprawnień P2P oraz uprawnień dotyczących USA i Kanady. Potwierdź z MultiTEL prawidłową konfigurację konta, zamiast traktować dane uwierzytelniające API jako automatyczne zezwolenie na wysyłanie dowolnego ruchu.
Żądanie wysłania
Uwierzytelnij się przez HTTPS przy użyciu aktywnego konta API, z dozwolonego dla niego źródłowego adresu IP. Przechowuj dane uwierzytelniające w magazynie sekretów po stronie serwera. Użyj metody POST z polami zakodowanymi jako formularz albo obiektu JSON, jeśli nie podajesz żadnych pól formularza ani parametrów zapytania. Nie umieszczaj danych uwierzytelniających ani treści wiadomości w adresie URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Pole | Wymagane | Znaczenie |
|---|---|---|
| from | Tak | Twój skonfigurowany numer nadawczy, najlepiej jako pełny ciąg cyfr w formacie międzynarodowym. |
| to | Tak | Jeden numer docelowy, numery docelowe oddzielone przecinkami lub tablica JSON. Najlepiej podawać pełne ciągi cyfr w formacie międzynarodowym. Żądanie grupowe może zostać odrzucone z powodu obowiązujących limitów P2P lub limitów krajowych; nie jest to API do nieograniczonej wysyłki masowej. |
| text | Dla SMS-ów | Treść wiadomości w kodowaniu UTF-8. Wymagany jest co najmniej niepusty tekst lub zawartość multimedialna. Wysyłaj rzeczywiste znaki i podziały wierszy zamiast kodu HTML lub tekstu zakodowanego procentowo. Niektóre ścieżki operatorów normalizują dosłowne ciągi sekwencji ucieczki. |
| media | Dla MMS-ów zawierających wyłącznie multimedia | Zawartość multimedialna zakodowana w Base64, a nie adres URL ani ścieżka pliku. Dostępność MMS-ów oraz ich format i rozmiar zależą od skonfigurowanej trasy. Potwierdź z MultiTEL obsługiwane multimedia; ten mechanizm obsługi nie ustanawia uniwersalnego limitu rozmiaru multimediów. |
| reference | Zalecane | Twoja etykieta korelacyjna, zachowywana w rekordach i powiadomieniach zwrotnych. Podaj ją, aby ułatwić rozwiązywanie problemów. Nie jest to klucz idempotencji. |
| notifyurl | Nie | Twój punkt odbioru powiadomień zwrotnych przez HTTPS. Po przetworzeniu mechanizm obsługi może wysłać wynik początkowy metodą POST. Musi to być punkt odbioru pod Twoją kontrolą, a jego adres URL nie może prowadzić do usługi wewnętrznej. |
W przypadku tablicy JSON użyj rzeczywistej tablicy w polu to; nie umieszczaj ciągu tekstowego reprezentującego tablicę JSON w polu formularza. Pierwszym testem integracji powinna pozostać wysyłka do pojedynczego odbiorcy. Obsługa grup i MMS-ów różni się w zależności od trasy, dlatego przed ich użyciem potwierdź, czy dane połączenie funkcji jest obsługiwane.
Odczytaj pełny wynik
Pokazano wyłącznie wybrane pola w celach ilustracyjnych; wyświetlony koszt nie jest wyceną.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Sprawdzaj łącznie status HTTP, pole status.code w JSON oraz pola status/message odpowiedzi. Kody wyników mogą być ciągami znaków. Zachowaj sms_log_id_ori oraz zwrócone wartości wiadomości i oznaczenia referencyjnego, aby dział wsparcia mógł powiązać dane. Wartości starszych pól uniqueid i pid różnią się w zależności od trasy; nie wywnioskuj ich formatu ani nie zakładaj, że są tokenami idempotencji klienta.
Success lub Message queued zwykle oznacza przyjęcie przez wybraną trasę, a nie odebranie wiadomości przez telefon danej osoby. Początkowy status powiadomienia zwrotnego, taki jak sent, sam w sobie nie potwierdza ostatecznego doręczenia.
Segmenty i opłaty
Zastosuj narzędzie Analiza długości SMS-a do całego ostatecznego tekstu przed wysłaniem. Ceny SMS-ów zależą od miejsca docelowego i usługi na koncie; obowiązujące opłaty operatora są doliczane za każdy segment. Ścieżka wysyłania sumuje ceny dla odbiorców i obowiązujące opłaty, a następnie mnoży tę sumę przez obliczoną liczbę segmentów SMS. Na potrzeby tego obliczenia traktuje żądanie MMS jako jedną wiadomość.
cost i permsg to sformatowane ciągi znaków przedstawiające kwoty pieniężne w starszej wersji odpowiedzi. carrier_fee_usd podaje składnik opłaty operatora w USD, który jest już uwzględniony w obliczonej łącznej kwocie wysyłki; nie doliczaj go ponownie. Sprawdź rzeczywiste ceny i dostępność tras dla swojego konta. Żądanie nie służy wyłącznie do sprawdzania ceny.
Przeanalizowany kod obciąża konto po pomyślnym przejściu ścieżki wysyłania przez operatora, ale przyjęcie przez operatora, lokalny zapis trwały i rozliczenie nie stanowią jednej transakcji. Błąd lub przekroczenie limitu czasu może wystąpić już po przyjęciu żądania przez system nadrzędny. Nie jest udostępniany klucz idempotencji klienta: ponowne użycie tego samego oznaczenia referencyjnego może spowodować ponowną wysyłkę i naliczenie opłat.
Doręczenie lokalne i wyniki mieszane
Wiadomości do numerów obsługiwanych lokalnie mogą zostać przyjęte (accepted) do procesu obsługi wiadomości przychodzących MultiTEL bez wysyłania przez zewnętrznego operatora. W przypadku żądania obejmującego wyłącznie numery lokalne odpowiedź może zawierać accepted, message_id, provider i delivery_status. Lokalne przyjęcie nie gwarantuje, że skonfigurowane u odbiorcy miejsce docelowe przekazywania zadziałało.
Sprawdź local_delivery_results i partial, jeśli występują. Dla odbiorcy pole accepted może mieć wartość true, mimo że przekazanie wiadomości się nie powiodło. W żądaniu mieszanym wiadomości do odbiorców obsługiwanych przez operatora mogą zostać przyjęte (accepted), a część lokalna może zakończyć się niepowodzeniem. Nie ponawiaj automatycznie całej partii: najpierw uzgodnij wynik dla każdego odbiorcy.
Przyjęcie żądania obejmującego wyłącznie numery lokalne wykazuje w tej ścieżce zerowy koszt wysyłki, ale odbiorcy nadal mogą ponosić standardowe opłaty za wiadomości przychodzące. Nie traktuj zerowego kosztu wysyłki jako gwarancji, że żadne konto nie zostanie obciążone.
Powiadomienia zwrotne i korelacja
Gdy podano notifyurl, początkowe powiadomienie zwrotne zawiera strukturę nadrzędną status oraz pola odpowiedzi, w tym message_id, reference, from, to, status, status_text, error_code, timestamp i accepted. Mogą też występować wyniki lokalne. Przechowuj informacje korelacyjne bez zapisywania w logach danych uwierzytelniających API ani zbędnych treści wiadomości.
Ten mechanizm obsługi nie dodaje pola podpisu do tego początkowego powiadomienia zwrotnego. Nie używaj niezweryfikowanego powiadomienia zwrotnego jako samodzielnej podstawy autoryzacji innego działania. Zapoznaj się z obsługiwaną konfiguracją integracji i webhooków dla swojego konta oraz wyjaśniaj niepewne wyniki na podstawie rekordów w portalu lub z pomocą działu wsparcia. Nie zakładaj, że powiadomienia zwrotne przychodzą tylko raz ani w kolejności ostatecznego doręczenia.
Błędy i bezpieczne wznawianie
Błędy walidacji mogą używać kodu API 403. Odmowy związane z zatwierdzeniem konta, P2P lub polityką krajową mogą również ustawiać status HTTP 403 i zawierać pole response.code przeznaczone do odczytu maszynowego. Ograniczenia częstotliwości mogą używać kodu 429 z informacjami o ponowieniu próby. Niedostępność polityki albo błąd wysyłania lub lokalnego zapisu trwałego może powodować kod 503 lub 500; starsza obsługa niewystarczającego salda może również zwracać 500.
W przypadku 429 przestrzegaj Retry-After oraz każdej podanej wartości response.retry_after. W przypadku odrzucenia związanego z kontem, nadawcą, krajem lub odbiorcą usuń przyczynę przed ponowieniem próby. W przypadku przekroczenia limitu czasu lub niejasnego wyniku wysyłki zachowaj czas żądania, oznaczenie referencyjne i zwrócone identyfikatory, sprawdź portal i skontaktuj się z działem wsparcia przed ponownym wysłaniem. Sam brak wpisu w logu nie dowodzi, że żaden operator nie przyjął żądania.