API SMS Cookbook

Wprowadzenie

Dowiedz się, jak wykorzystać różne możliwe kombinacje API dla platformy SMS OVHcloud.

Wysyłka SMS na bieżąco

Wysyłka SMS na bieżąco odpowiada wywołaniu usługi sieciowej w celu regularnego wysyłania SMS-ów pojedynczo. Dla każdego SMS-a do wysłania wykonujemy więc wywołanie usługi sieciowej w POST do następującej metody:

ServiceName odpowiada Twojemu kontu SMS. Możesz go uzyskać w Panelu klienta lub wykonując wywołanie GET do następującej metody:

Oto przykład: /sms/sms-XXXXXX-1/jobs

Parametry obowiązkowe:

• ServiceName
• Message (Twoja wiadomość; zwróć uwagę na jej długość, a także na dodanie klauzuli STOP, na kodowanie i znaki specjalne, które mogą zużywać więcej kredytów SMS)

Odbiorcy:

• Receivers (lista numerów; dla SMS-ów wysyłanych na bieżąco jest to zalecany parametr z jednym numerem)
• receiversDocumentUrl (adres URL wskazujący na plik CSV zawierający numery odbiorców)
• receiversSlotId (ID wskazujące na wcześniej wczytany plik CSV)

Nadawca

• sender (wybór nazwy nadawcy, abyś był od razu rozpoznawany jako nadawca SMS-a)
• senderForResponse (użycie numeru skróconego umożliwiającego dwukierunkową odpowiedź SMS)

Inne

• charset
• class (typ wysyłanego SMS-a)
• coding (kodowanie na 7 lub 8 bitów; wpływa to na liczbę znaków dostępnych na kredyt SMS)
• differedPeriod (zaplanowanie wysyłki)
• noStopClause (pozwala wskazać, że jest to SMS niekomercyjny; wzmianka jest usuwana z wiadomości)
• priority (wskazanie priorytetu)
• tag (oznaczenie służące do kategoryzacji wiadomości)
• validityPeriod (czas wygaśnięcia wiadomości w razie problemu z jej dostarczeniem)

Wysyłka masowa

Aby wysłać tę samą wiadomość do dużej liczby odbiorców, ponownie wykorzystujemy tę samą metodę POST, tym razem jednak importując plik CSV za pośrednictwem adresu URL:

Dostępne są dwa podejścia.

Pierwsze korzysta bezpośrednio z parametru receiversDocumentUrl (adres URL wskazujący na plik CSV zawierający numery odbiorców) z powyższą metodą.

Drugie najpierw wczytuje plik CSV za pomocą następującej metody, używając parametrów serviceName, csvUrl, description i slotId:

Po wczytaniu pliku wystarczy ponownie wywołać metodę jobs z parametrem receiversSlotId, wskazując właściwe SlotId:

Mailing

Wysyłka masowa z mailingiem opiera się na wysyłce masowej oraz na utworzeniu specjalnego pliku kontaktów CSV powiązanego z wiadomością. Wiadomości będą mogły zawierać pola zmienne. Wywołując nazwę kolumny, oto przykład ilustrujący ten przypadek użycia:

plik contacts.csv

number ;lastname ;firstname ;address
0662000000 ;Durant ;Pierre ;xx rue montaigne Paris
0662000001 ;Dupont ;Jean ;xx rue montaigne Paris
...

Wiadomość:

Hello #firstname# #lastname#, your order will be delivered to the following address: #address#. Best regards.

Monitorowanie kampanii

Podczas tworzenia wysyłki za pomocą metody POST jobs możesz podać wartość dla parametru tag:

Parametr ten pozwoli Ci następnie śledzić wiadomości wysłane z tym tagiem.

Aby pobrać wszystkie identyfikatory wiadomości wychodzących, użyj następującej metody, podając parametr tag jako filtr zapytania:

Aby pobrać wszystkie szczegóły każdej wiadomości, użyj:

Dzięki tym informacjom możesz tworzyć raporty zbiorcze dla każdej kampanii. Oto kilka przykładów informacji: wskaźnik dostarczonych wiadomości, wskaźnik błędów, czas dystrybucji wiadomości itp.

Aby śledzić ewolucję swoich STOP SMS i reagować, jeśli kampania SMS generuje wysoki wskaźnik rezygnacji z subskrypcji, użyj:

Odpowiedź SMS

Aby skorzystać z odpowiedzi SMS, musisz wysyłać swoje SMS-y z numerem skróconym, używając parametru senderForResponse.

Aby skonfigurować wywołanie Callback przy każdej otrzymanej odpowiedzi, dzięki czemu będziesz powiadamiany o odpowiedziach w czasie rzeczywistym, użyj następującej metody:

W podejściu Pull możesz zdecydować się na przeglądanie otrzymanych odpowiedzi, wywołując następującą metodę:

Zamawianie kredytów SMS

Aby automatycznie generować zamówienia SMS, wywołaj następującą metodę, podając jako parametry konto SMS do zasilenia oraz kwotę kredytów, którą chcesz kupić:

W zamian otrzymasz wszystkie informacje o cenach netto, brutto, rabatach, a także umowy i link do zamówienia w celu dokonania płatności.

Wcześniej możesz uzyskać ceny w zależności od żądanej ilości za pomocą następującej metody:

Zarządzanie użytkownikami

Dla każdego konta SMS możesz tworzyć użytkowników, którzy będą mogli mieć własne wysyłki oraz różne reguły zarządzania pozwalające w szczególności na stosowanie limitów wysyłek.

Pierwszym krokiem jest utworzenie użytkownika:

Następnie skonfigurowanie jego ustawień (callback, limit, IP itp.):

Na koniec możesz sprawdzić stan zużycia użytkownika:

Możesz również śledzić zużycie, używając tagu kampanii lub tożsamości nadawcy (sender) za pomocą następującej metody, a także określić okres, na przykład w celu refakturowania zużycia miesiąc po miesiącu:

Transfer kredytów

Jeśli zarządzasz kilkoma kontami SMS (serviceName: sms-XXXX-1, sms-XXXXX-2 itp.), możesz przenosić kredyty między swoimi różnymi kontami. W tym celu użyj następującej metody, wskazując konto SMS do obciążenia, konto do zasilenia oraz na koniec kwotę kredytów do przeniesienia:

Ten mechanizm jest bardzo przydatny do niezależnego zarządzania kilkoma kontami SMS, w szczególności w przypadku odsprzedaży różnym podmiotom. Aby odizolować konta, musisz skonfigurować odrębne Tokeny w celu odizolowania uprawnień. Operację tę wykonuje się podczas tworzenia Tokenów aplikacji: w uprawnieniach musisz wyraźnie określić, że dana aplikacja ma uprawnienia tylko do ServiceName określonego w autoryzowanych adresach URL.

Sprawdź również

Dołącz do grona naszych użytkowników.