Redlink.pl Web Services API Wersja 1.3 (19.09.2011) - 1 -
Spis treści Wstęp.... 4 1 Kontakty... 5 1.1 Opis i typy... 5 1.2 AddContact... 6 1.3 AddContactsToGroup... 6 1.4 ChangeContact... 7 1.5 DeleteAllContactsInGroup... 7 1.6 DeleteContacts... 7 1.7 DeleteContactsFromGroup... 8 1.8 GetAllContactsFromGroup... 8 1.9 GetContact... 9 1.10 IsContactInArchive... 9 1.11 MoveContactFromArchive... 9 1.12 MoveContactToArchive... 10 1.13 SearchContacts... 10 1.14 GetAllContactsFromArchive... 11 2 Grupy... 12 2.1 Opis... 12 2.2 AddGroup... 12 2.3 ChangeGroup... 12 2.4 DeleteGroup... 13 2.5 GetAllGroups... 13 2.6 GetGroup... 14 2.7 GetGroupContactsCount... 14 2.8 GroupContainsContact... 14 3 Pola indywidualne... 15 3.1 Opis... 15 3.2 ChangeContactsFieldNames... 16 3.3 GetContactsFieldsNames... 16 4 Kampanie faksowe... 17 4.1 Opis i typy... 17-2 -
4.2 CreateFaxCampaign... 18 4.3 GetFaxCampaignData... 19 4.4 GetFaxCampaignState... 19 4.5 GetFaxResults... 20 5 Kampanie SMS-owe... 20 5.1 Opis... 20 5.2 CreateSmsCampaign... 21 5.3 GetSmsCampaignData... 22 5.4 GetSmsCampaignState... 22 5.5 GetSmsResults... 23 6 Kampanie głosowe... 24 6.1 Opis... 24 6.2 CreateCallerCampaign... 25 6.3 GetCallerCampaignData... 26 6.4 GetCallerCampaignState... 26 6.5 GetCallerResults... 27 7 Kampanie mailowe... 28 7.1 Opis... 28 7.2 CreateMailCampaign... 30 7.3 GetMailCampaignData... 30 7.4 GetMailCampaignState... 31 7.5 GetMailResults... 31 7.6 GetTrackingReport... 31 7.7 GetMailCampaignStatistics... 32 8 PDF Konwerter... 33 8.1 Opis... 33 8.2 ConvertFileToPdf... 33 9 Przykłady... 34 9.1 PHP... 34 9.2 C#... 35 9.3 Java... 35-3 -
Wstęp. Redlink.pl API to zestaw metod i funkcji pozwalających na pełną integrację usług faksowych, głosowych, sms-owych i konwersji Pdf z dowolnym oprogramowaniem klienta. API wykorzystuje standardy Web Services, w szczególności WSDL, SOAP oraz XML. Więcej informacji na ich temat można uzyskać na stronach : http://www.w3.org/tr/wsdl http://www.w3.org/tr/soap http://www.w3.org/tr/rec-xml/ Do integracji wybranych usług z własnym serwisem nie jest niezbędna dogłębna znajomość tych technologii ponieważ w praktyce każde środowisko programistyczne posiada gotowe biblioteki obsługujące Web Services i wywołanie odpowiedniej usługi sprowadza się do kilku linijek prostego kodu. Platforma Biblioteka Web Services Linki.NET (C#,.NET Framework posiada wbudowaną przestrzeń nazw http://msdn.microsoft.com/webservices/ C++, Visual System.Web. Zawiera klasy i interfejsy umożliwiające Basic) komunikację z serwerami internetowymi, a także klasy kontrolek Web Forms oraz usług internetowych XML Web Services. Java Najpopularniejsze Web Services Framework dla języka Java to Apache Axis, GlassFish(metro) oraz CFX. https://metro.dev.java.net/ http://incubator.apache.org/cxf/ http://ws.apache.org/axis2/ PHP Od wersji PHP 5 dostępna jest wbudowana implementacja protokołu SOAP (SOAP Extension). Dodatkowo można skorzystać z oddzielnych rozszerzeń np. http://pl.php.net/soap http://sourceforge.net/projects/nusoap/ http://pear.php.net/package/soap NuSOAP lub PEAR (dla php4). PERL Moduł SOAP::Lite http://www.soaplite.com/ Python Biblioteka Python Web Services http://pywebsvcs.sourceforge.net/ Ruby on Biblioteka Action Web Services http://www.rubyonrails.org/ Rails W momencie podpisania umowy, użytkownik otrzymuje login i hasło do systemu. Parametry te wykorzystuje się w wywołaniach wszystkich metod serwisu. Przykłady wywołania konkretnych metod można znaleźć w ostatnim rozdziale tego dokumentu. Każde wywołanie metody kończy się kodem błędu według poniższego zestawienia : Kod Opis 0 Ok - wywołanie zakończone pomyślnie 1 ValidationError - błąd podczas walidacji danych wejściowych 2 AuthenticationError - błąd logowania do systemu 3 AuthorizationError - błąd braku uprawnień 4 DatabaseError - błąd bazy danych 5 OperationError - błąd wykonywania operacji 6 RuntimeError - niezdefiniowany błąd - 4 -
1 Kontakty 1.1 Opis i typy Adres : https://redlink.pl/ws/v1/soap/contacts/contacts.asmx WSDL : https://redlink.pl/ws/v1/soap/contacts/contacts.asmx?wsdl Zestaw metod pozwalających na pełne zarządzanie kontaktami. Uwaga : Zarządzanie kontaktami jest funkcjonalnością opcjonalną w systemie Redlink.pl. Wysłanie faksu, smsa, czy wiadomości głosowej nie wymaga dodania kontaktu do bazy systemu. Przechowywanie bazy kontaktów po stronie systemu Redlink.pl przydaje się w momencie korzystania z panelu klienta (https://redlink.pl/app/panel) i potrzeby synchronizacji z zewnętrzną bazą kontaktów. W wywołaniach i odpowiedziach wykorzystywany jest typ ContactData o następującej strukturze. ContactData ContactId string Identyfikator kontaktu z systemu klienta (dowolny unikalny ciąg znaków). Parametr opcjonalny, jeżeli nie zostanie podany system sam ustawi te pole. Email string Poprawny adres email. Wymagane jest podanie przynajmniej jednego z pól : email, MobilePhone, StatPhone lub Fax. FirstName string Imię, opcjonalne. LastName string Nazwisko, opcjonalne. StatPhone string Telefon stacjonarny (format 0618222222 lub 0032 dla międzynarodowych) Address string Adres, opcjonalne. City string Miejscowość, opcjonalne. Zip string Kod, format XX-XXX, opcjonalne. Country string Kraj, opcjonalne. CompanyName string Nazwa firmy, opcjonalne. JobTitle string Stanowisko, opcjonalne. MobilePhone string Telefon komórkowy (format 0502222222) Fax string Numer faksowy (format 0618222222) Datetime1, Datetime2, datetime Pięć pól czasowych do dowolnego wykorzystania. Opcjonalne. Datetime3, Datetime4, Datetime5 String1, string Pięć pól znakowych do dowolnego wykorzystania. Opcjonalne. String2, String3, String4, String5 Bool1, Bool2, Bool3, Bool4, boolean Pięć pól logicznych do dowolnego wykorzystania. Opcjonalne. - 5 -
Bool5 Numeric1, Numeric2, Numeric3, Numeric4, Numeric5 decimal Pięć pól liczbowych do dowolnego wykorzystania. Opcjonalne. 1.2 AddContact Dodanie kontaktu do systemu Redlink.pl. ContactData complex Struktura zawierająca dane nowo tworzonego kontaktu (patrz Wstęp) Data string Identyfikator kontaktu, przypisany przez system jeżeli nie został podany jako parametr. 1.3 AddContactsToGroup Przypisanie kontaktu do wybranej grupy (patrz rozdział grupy). arcontactids string array Zewnętrzne identyfikatory kontaktów strgroupid string Zewnętrzny identyfikator grupy Data int Liczba kontaktów dodanych do grupy. - 6 -
1.4 ChangeContact Zmiana danych kontaktu (metoda działa na zasadzie zastąpienia istniejących danych, tymi podanymi w parametrze). strcontactid string Identyfikator zmienianego kontaktu data complex Struktura zawierająca nowe dane kontaktu. 1.5 DeleteAllContactsInGroup Usunięcie wszystkich przypisań kontaktów do tej grupy (bez usunięcia samych kontaktów). strgroupid string Identyfikator grupy 1.6 DeleteContacts Usunięcie kontaktów z bazy redlink.pl. Aby móc usunąć kontakt, musi znajdować się w archiwum. arcontactids string array Identyfikatory usuwanych kontaktów. - 7 -
1.7 DeleteContactsFromGroup Usunięcie przypisania wybranych kontaktów do danej grupy. arcontactids string array Identyfikatory kontaktów. strgroupid string Identyfikator grupy. data int Liczba usuniętych kontaktów. 1.8 GetAllContactsFromGroup Pobranie wszystkich kontaktów z danej grupy. strgroupid string Identyfikator grupy. Aby wyciągnąć wszystkie kontakty, należy podać grupę o identyfikatorze ALLCONTACTS. ioffset int Przesunięcie według listy wyników (zaczynając od zera). ilimit int Limit liczby wyników (max 1000). data complex array Tablica z danymi wszystkich kontaktów. - 8 -
1.9 GetContact Pobranie danych kontaktu. strcontactid string Identyfikator kontaktu. ContactData complex Struktura zawierająca dane kontaktu. 1.10 IsContactInArchive Sprawdza czy kontakt znajduje się w archiwum. strcontactid string Identyfikator kontaktu. InArchive boolean Czy kontakt w archiwum. ArchiveReason string Powód przeniesienia do archiwum. 1.11 MoveContactFromArchive Przywrócenie kontaktu z archiwum. - 9 -
strcontactid string Identyfikator kontaktu. 1.12 MoveContactToArchive Przeniesienie kontaktu do archiwum. strcontactid string Identyfikator kontaktu. strreasoncode string Powód przeniesienia do archiwum: UNREGISTERED - wyrejestrowany DOESNOTEXISTS - nie istnieje 1.13 SearchContacts Wyszukanie kontaktów. data complex Przekazanie danych do wyszukiwania. ioffset int Przesunięcie według listy wyników (zaczynając od zera). ilimit int Limit liczby wyników (max. 1000). - 10 -
ContactCount int Liczba wyszukanych kontaktów data Complex array Struktura zawierająca dane kontaktów. 1.14 GetAllContactsFromArchive Pobranie wszystkich kontaktów z archiwum. ioffset int Przesunięcie według listy wyników (zaczynając od zera). ilimit int Limit liczby wyników (max. 1000). ContactCount int Liczba wyszukanych kontaktów ArchiveContactIdArray Complex array Lista identyfikatorów kontaktów - 11 -
2 Grupy 2.1 Opis Adres : https://redlink.pl/ws/v1/soap/contacts/groups.asmx WSDL : https://redlink.pl/ws/v1/soap/contacts/groups.asmx?wsdl Zestaw metod pozwalających na zarządzanie grupami kontaktów. Uwaga : Zarządzanie grupami jest funkcjonalnością opcjonalną w systemie Redlink.pl. Wysłanie faksu, smsa, czy wiadomości głosowej nie wymaga wcześniejszego tworzenia grupy w systemie. Typ GroupData GroupId string Identyfikator grupy z systemu klienta (dowolny unikalny ciąg znaków). GroupName string Nazwa grupy. Jeżeli nie zostanie podany, system wygeneruje go automatycznie. 2.2 AddGroup Dodanie nowej grupy. data GroupData Dane nowo tworzonej grupy. Data string Identyfikator nowo tworzonej grupy. 2.3 ChangeGroup Zmiana danych grupy. strgroupid string Identyfikator zmienianej grupy data GroupData Nowe dane grupy - 12 -
2.4 DeleteGroup Usunięcie grupy z systemu. Grupa nie może mieć przypisanych kontaktów. strgroupid string Identyfikator usuwanej grupy 2.5 GetAllGroups Pobranie wszystkich grup utworzonych w systemie. DataArray GroupData array Lista grup - 13 -
2.6 GetGroup Pobiera dane grupy. strgroupid string Identyfikator grupy GroupData complex Dane grupy 2.7 GetGroupContactsCount Pobranie liczby kontaktów przypisanych do grupy. strgroupid string Identyfikator grupy Data int Liczba kontaktów przypisanych do grupy 2.8 GroupContainsContact Sprawdzenie czy dany kontakt jest przypisany do danej grupy. - 14 -
strcontactid string Identyfikator kontaktu strgroupid string Identyfikator grupy Data boolean Informacja czy kontakt jest przypisany do grupy. 3.1 Opis 3 Pola indywidualne Adres : https://redlink.pl/ws/v1/soap/contacts/fielddefinitions.asmx WSDL : https://redlink.pl/ws/v1/soap/contacts/fielddefinitions.asmx?wsdl Ta grupa funkcji pozwala na definiowanie dodatkowych pól opisujących kontakty, do dyspozycji jest 5 pól typu string, 5 pól typu DateTime, 5 pól typu boolean i 5 pól typu Decimal. Typ ContactsFieldsNamesData opisujący strukturę nazw: DateTime1Name string Nazwa pola DateTime2Name string Nazwa pola DateTime3Name string Nazwa pola DateTime4Name string Nazwa pola DateTime5Name string Nazwa pola String1Name string Nazwa pola String2Name string Nazwa pola String3Name string Nazwa pola String4Name string Nazwa pola String5Name string Nazwa pola Bool1Name string Nazwa pola Bool2Name string Nazwa pola Bool3Name string Nazwa pola Bool4Name string Nazwa pola Bool5Name string Nazwa pola Numeric1Name string Nazwa pola Numeric2Name string Nazwa pola Numeric3Name string Nazwa pola Numeric4Name string Nazwa pola Numeric5Name string Nazwa pola - 15 -
3.2 ChangeContactsFieldNames Zmienia nazwy indywidualnych pól. ContactsFieldsNamesData complex Nowe nazwy indywidualnych pól. 3.3 GetContactsFieldsNames Pobiera aktualne nazwy pól. Data complex Nazwy indywidualnych pól. - 16 -
4 Kampanie faksowe 4.1 Opis i typy Adres : https://redlink.pl/ws/v1/soap/faxcampaigns/faxcampaigns.asmx WSDL : https://redlink.pl/ws/v1/soap/faxcampaigns/faxcampaigns.asmx?wsdl Zestaw funkcji odpowiedzialnych za wysyłkę faksów oraz pobranie wyników. Typ FaxCampaignData opisujący strukturę kampanii faksowej: CampaignId string Zewnętrzny identyfikator kampanii. Wymagana unikalność. Opcjonalny parametr (system sam go wygeneruje, jeżeli nie zostanie podany). Name string Nazwa kampanii faksowej. Pole obowiązkowe. Description String Opis kampanii faksowej. Pole opcjonalne. ConfirmationMail String Adres email na który przyjdzie potwierdzenie wysłania kampanii. Pole opcjonalne. FileName String Nazwa pliku. Pole obowiązkowe. FileContent base64binary Treść pliku zakodowana base64. Jedno z 3 pól musi zostać podane : FileContent, FileURL lub WebSiteUrl. FileURL string Adres pliku, jeżeli ma zostać pobrany przez program wysyłający. WebSiteUrl string Adres strony www,która ma być wysłana w postaci faksu. ConvertedPageOrientation Int Orientacja strony (pionowa 1, pozioma 2). Pole opcjonalne. GroupId string Identyfikator grupy kontaktów, jeżeli wysyłka ma się opierać na kontaktach wprowadzonych do systemu Redlink.pl. Jedno z 3 pól musi zostać podane : Group Id, ContactId lub Numbers. ContactId string Identyfikator kontaktu na który ma zostać wysłany faks Numbers ArrayOfString Lista numerów, na który ma zostać wysłany faks, format numeru to 0YYXXXXXXX, gdzie YY to numer strefy np. 0618111111. Można podać maksymalnie 1000 numerów w jednej kampanii. Dla numerów międzynarodowych format wygląda następująco 00YYXXXXXXXXX, gdzie YY to kierunkowy do danego kraju. FaxLogin string Login faksu przy pomocy którego będzie wysyłana wiadomość. Pole obowiązkowe. ScheduleTime datetime Czas wysyłki faksu (może być odłożony w przyszłości). Nie wypełnienie tego pola spowoduje ustawienie czasu na aktualny. Repeat int Informacja czy w przypadku błędu faks ma być powtarzany. Jeżeli pole to zostanie ustawione, w przypadku błędu faks zostanie automatycznie ponowiony po 5,10 i 15 minutach. Pole to może przyjmować następujące wartości: 0 brak powtórek, 1 powtarzanie wszystkich błędnych wysyłek faksów, 2 powtarzanie tylko w przypadku gdy połączenie nie zostanie odebranie, linia będzie zajęta lub wystąpi błąd braku sygnału faksu. VoiceResponseType int Pozwala na ustawienie zapowiedzi głosowej odgrywanej każdorazowo po nawiązaniu połączenia (przed wysyłką właściwego pliku). Pole to może - 17 -
przyjmować następujące wartości: 1 brak zapowiedzi, 2 zapowiedź w języku polskim, 3 zapowiedź w języku angielskim. Pole jest opcjonalne (wartością domyślną w przypadku jego pominięcia jest 1). Typ FaxSendResult opisujący rezultat pojedynczej wysyłki. ContactId string Identyfikator kontaktu jeżeli był podany Number string Numer jeżeli był podany. ResultCode string Ostanie kod rezultatu (w przypadku ustawienia powtórek może się jeszcze zmienić, ostateczny wynik uzależniony jest od pola Finished): FAX_SEND_OK faks wysłany poprawnie FAX_LINE_BUSY linia zajęta FAX_NO_FAX_SIGNAL brak sygnału faksu FAX_TRANSMISSION_ERROR błąd transmisji faksu FAX_INCORRECT_NUMBER- niepoprawny numer FAX_RESULT_UNKNOWN neizdefiniowany błąd ResultDetails string Szczegóły rezultatu (komentarz). Finished Boolean True jeżeli wysyłka dla tego kontaktu/numeru została zakończona. Generalnie wysyłkę faksową można zrealizować na dwa sposoby. Pierwszy sposób polega na wykorzystaniu bazy kontaktów zawartej w systemie Redlink.pl (sposób tworzenia kontaktów i grup został omówiony w poprzednich rozdziałach), przy tej opcji należy posługiwać się identyfikatorami : GroupId oraz ContactId. System automatycznie pobierze dla nich numery faksów i wyśle wiadomość. Drugi sposób polega na wypełnieniu docelowymi numerami tablicy Numbers, w tym układzie pola GroupId oraz ContactId zostawiamy puste. Treść faksu podajemy albo w formie zakodowanej base64 (pole FileContent) lub w postaci linku URL (np. http://www.redlink.pl/dok.pdf) lub w postaci adresu URL wybranej strony (program ją automatycznie zaciągnie i zamieni w faks). Platforma Redlink.pl obsługuje następujące typy plików : pdf, doc, docx, html, htm, xls, xlix, ppt, pptx, jpeg, jpg, gif, bmp. 4.2 CreateFaxCampaign Stworzenie i wysłanie kampanii faksowej. FaxCampaignData complex Struktura zawierająca opis kampanii - 18 -
Description string Opis tekstowy wyniku Data string Identyfikator kampanii. 4.3 GetFaxCampaignData Pobranie informacji o wybranej kampanii. strcampaignid string Identyfikator kampanii. FaxCampaignData complex Struktura zawierająca opis kampanii. 4.4 GetFaxCampaignState Pobranie status kampanii. Status określa czy dana kampania została już wysłana. strcampaignid string Identyfikator kampanii. Data string Stan kampanii. Możliwe stany to : READYTOSEND - kampania gotowa do wysyłki SENDING - kampania w trakcie wysyłki DELIVEREDTOSEND - kampania wysłana, trwa pobieranie jej wyników SENT - kampania wysłana - 19 -
4.5 GetFaxResults Pobranie informacji o wysyłce faksowej. strcampaignid string Identyfikator kampanii. Data FaxSendResult Array Lista rezultatów kampanii. 5.1 Opis 5 Kampanie SMS-owe Adres : https://redlink.pl/ws/v1/soap/smscampaigns/smscampaigns.asmx WSDL : https://redlink.pl/ws/v1/soap/smscampaigns/smscampaigns.asmx?wsdl Zestaw funkcji odpowiedzialnych za wysyłkę smsów oraz pobranie wyników. Typ SmsCampaignData opisujący strukturę kampanii sms-owej: CampaignId string Zewnętrzny identyfikator kampanii. Wymagana unikalność. Pole opcjonalne, w przypadku braku, system sam wygeneruje jego wartość. Name string Nazwa kampanii. Pole obowiązkowe. Description string Opis kampanii. Pole opcjonalne. ConfirmationMail string Adres email na który pójdzie potwierdzenie dostarczenia kampanii. Pole opcjonalne. Message string Treść wiadomości, może być dłuższa niż 160 znaków,w takim przypadku zostanie wysłanych więcej smsów stanowiących całość na zasadzie : Liczba znaków Liczba smsów 1-160 1 161-306 2-20 -
307-459 3 460-612 4 GroupId string Identyfikator grupy (zasada działania analogiczna jak dla faksów). Wymagane jedno z pól : GroupId, ContactId lub Numbers. ContactId string Identyfikator kontaktu (zasada działania analogiczna jak dla faksów). Numbers ArrayOfString Lista numerów na które ma zostać wysłana kampania, format numeru komórkowego to 0500111111 SenderId string Tekst, który pojawi się jako nadawca. W przypadku SMS-ów Pro 11- znakowy tekst, wcześniej zautoryzowany w panelu Redlink.pl. W przypadku SMS-ów Eco wartość pusta (SMS przyjdzie z losowego numeru) ScheduleTime datetime Czas wysłania kampanii. Opcjonalne w przypadku nie wypełnienia pola system ustawi czas na aktualny. Analogicznie jak dla faxów, wysyłkę sms-ową można oprzeć na wcześniej utworzonych kontaktach lub bezpośrednio podać listę numerów. Typ SmsSendResult opisujący rezultat pojedynczej wysyłki. ContactId string Identyfikator kontaktu jeżeli był podany Number string Numer jeżeli był podany. ResultCode string Kod rezultatu. SMS_SEND sms wysłany SMS_ERROR wystąpił błąd ResultDetails string Szczegóły rezultatu (komentarz). Finished Boolean True jeżeli wysyłka dla tego kontaktu/numeru została zakończona. 5.2 CreateSmsCampaign Stworzenie i wysłanie kampanii smsowej. SmsCampaignData complex Struktura zawierająca opis kampanii - 21 -
Data string Identyfikator kampanii. 5.3 GetSmsCampaignData Pobranie informacji o wybranej kampanii. strcampaignid string Identyfikator kampanii. SmsCampaignData complex Struktura zawierająca opis kampanii. 5.4 GetSmsCampaignState Pobranie status kampanii. Status określa czy dana kampania została już wysłana. strcampaignid string Identyfikator kampanii. Data string Stan kampanii. Możliwe stany to : READYTOSEND - kampania gotowa do wysyłki SENDING - kampania w trakcie wysyłki DELIVEREDTOSEND - kampania wysłana, trwa pobieranie jej wyników SENT - kampania wysłana - 22 -
5.5 GetSmsResults Pobranie informacji o wysyłce sms-owej. strcampaignid string Identyfikator kampanii. Data SmsSendResult Array Lista rezultatów kampanii. - 23 -
6 Kampanie głosowe 6.1 Opis Adres : https://redlink.pl/ws/v1/soap/callercampaigns/callercampaigns.asmx WSDL : https://redlink.pl/ws/v1/soap/callercampaigns/callercampaigns.asmx?wsdl Zestaw funkcji odpowiedzialnych za wysyłkę wiadomości głosowych oraz pobranie wyników. Typ CallerCampaignData opisujący strukturę kampanii głosowej: CampaignId string Zewnętrzny identyfikator kampanii. Wymagana unikalność. Opcjonalny parametr (system sam go wygeneruje, jeżeli nie zostanie podany). Name string Nazwa kampanii. Pole obowiązkowe. Description String Opis kampanii. Pole opcjonalne. ConfirmationMail String Adres email na który przyjdzie potwierdzenie wysłania kampanii. Pole opcjonalne. FileName String Nazwa pliku. Pole musi być wypełnione jeśli wysłany w ramach kampanii ma zostać plik dźwiękowy FileContent base64binary Treść pliku zakodowana base64. W przypadku gdy wysyłany w ramach kampanii jest plik dźwiękowy jedno z 2 pól musi zostać podane : FileContent, FileURL. Wymagany jest.wav, format 16 bit, częstotliwość próbkowania 8000 Hz (co daje szybkość transmisji bitów: 128 kb/s) FileURL string Adres pliku, jeżeli ma zostać pobrany przez program wysyłający. TextMessage string Treść tekstowa wiadomości która ma zostać odczytana przez syntezator mowy zamiast odgrywania pliku dźwiękowego *. GroupId string Identyfikator grupy kontaktów, jeżeli wysyłka ma się opierać na kontaktach wprowadzonych do systemu Redlink.pl. Jedno z 3 pól musi zostać podane : Group Id, ContactId lub Numbers. ContactId string Identyfikator kontaktu na który ma zostać wysłana wiadomość głosowa. Numbers ArrayOfString Lista numerów, na który ma zostać wysłana wiadomość głosowa, format numeru to 0YYXXXXXXX, gdzie YY to numer strefy np. 0618111111. Można podać maksymalnie 1000 numerów w jednej kampanii. Dla numerów międzynarodowych format wygląda następująco 00YYXXXXXXXXX, gdzie YY to kierunkowy do danego kraju. ContactNumberType int Pole obowiązkowe w przypadku podania GroupId lub ContactId. Określa na który numer z kontaktu ma zostać wysłana wiadomość. Możliwe wartości : 1-telefon komórkowy 2-telefon stacjonarny 3-telefon komórkowy lub stacjonarny (jeśli nie ma komórkowego) 4-telefon stacjonarny lub komórkowy (jeśli nie ma stacjonarnego) CallerLogin string Login obiektu caller przy pomocy którego będzie wysyłana wiadomość. Pole obowiązkowe. ScheduleTime datetime Czas wysyłki faksu (może być odłożony w przyszłości). Nie wypełnienie - 24 -
tego pola spowoduje ustawienie czasu na aktualny. SendDeadline datetime Czas po którym wysyłka zostanie przerwana. Pole wykorzystywane, aby uniknąć wysyłki wiadomości np.. w nocy. Repeat int Informacja czy w przypadku błędu wysyłki, wiadomość ma być powtarzana. Jeżeli pole zostanie ustawione, w przypadku błędu każda wiadomość zostanie automatycznie ponowiona po 5,10 i 15 minutach. RedirectKey short Opcja pozwala na przekierowanie rozmówcy na wybrany numer po wciśnięciu danego (to określa ten parametr) klawisza w telefonie. Pozwala na realizację scenariusza : Telefon dzwoni do klienta i odczytuje wiadomość Dzień dobry. Mamy nową promocję. Wciśnij jeden, aby połączyć się z naszym Biurem Obsługi Klienta. RedirectNumber String Na ten numer zostanie wykonane przekserowanie, o którym mowa powyżej. Analogicznie jak dla faxów, wysyłkę głosową można oprzeć na wcześniej utworzonych kontaktach lub bezpośrednio podać listę numerów. * Opcją nową w stosunku do faxów jest możliwość wysłania kampanii z podaniem tekstu, który ma być odczytany przez syntezator mowy. Korzystając z opcji wysyłania tekstu zamiast pliku należy pamiętać że: ciągi liczb cyfr o długości mniejszej niż 2 cyfry zostaną zinterpretowane, tzn. 21 zostanie przekształcone na dwadzieścia jeden, wyrazy zapisane przy pomocy wielkich liter zostaną przeliterowane np."onz" zostanie zamienione na "o en zet", interpretowane są daty w formatach: DD.MM.RRRR, DD-MM-RRRR lub RRRR.MM.DD, RRRR-MM- DD oraz godziny w formacie GG:MM. Typ CallerSendResult opisujący rezultat pojedynczej wysyłki. ContactId string Identyfikator kontaktu jeżeli był podany Number string Numer jeżeli był podany. ResultCode string Kod rezultatu. CALLER_RECEIVED caller wysłany CALLER_NOT_RECEIVED caller nie został odebrany CALLER_BEYONDCAMPAIGNTIME wiadomość nie została wysłana ponieważ czas wysyłki został przekroczony CALLER_HANGUP caller został przerwany przed odsłuchaniem pełnej wiadomości ResultDetails string Szczegóły rezultatu (komentarz). Finished Boolean True jeżeli wysyłka dla tego kontaktu/numeru została zakończona. 6.2 CreateCallerCampaign Stworzenie i wysłanie kampanii głosowej. - 25 -
CallerCampaignData complex Struktura zawierająca opis kampanii Data string Identyfikator kampanii. 6.3 GetCallerCampaignData Pobranie informacji o wybranej kampanii. strcampaignid string Identyfikator kampanii. CallerCampaignData complex Struktura zawierająca opis kampanii. 6.4 GetCallerCampaignState Pobranie status kampanii. Status określa czy dana kampania została już wysłana. strcampaignid string Identyfikator kampanii. - 26 -
Data string Stan kampanii. Możliwe stany to : READYTOSEND - kampania gotowa do wysyłki SENDING - kampania w trakcie wysyłki DELIVEREDTOSEND - kampania wysłana, trwa pobieranie jej wyników SENT - kampania wysłana 6.5 GetCallerResults Pobranie informacji o wysyłce głosowej. strcampaignid string Identyfikator kampanii. Data CallerSendResult Array Lista rezultatów kampanii. - 27 -
7 Kampanie mailowe 7.1 Opis Adres : https://redlink.pl/ws/v1/soap/mailcampaigns/mailcampaigns.asmx WSDL : https://redlink.pl/ws/v1/soap/mailcampaigns/mailcampaigns.asmx?wsdl Zestaw funkcji odpowiedzialnych za wysyłkę kampanii mailowych oraz pobranie wyników. Typ MailCampaignData opisujący strukturę kampanii mailowej: CampaignId string Zewnętrzny identyfikator kampanii. Wymagana unikalność. Opcjonalny parametr (system sam go wygeneruje, jeżeli nie zostanie podany). Name string Nazwa kampanii. Pole obowiązkowe. Description string Opis kampanii. Pole opcjonalne. Subject string Temat widomości email. Pole obowiązkowe. FromName string Adres From nazwa nadawcy. Pole obowiązkowe. FromAddress string Adres From adres email nadawcy. Pole obowiązkowe. Adres musi być zautoryzowany w Panelu Redlink.pl (Ustawienia -> Lista adresów). ReplyTo string Adres ReplyTo. Adres musi być zautoryzowany w Panelu Redlink.pl (Ustawienia -> Lista adresów). Pole opcjonalne, w przypadku braku system przyporządkuje adres nadawcy (z pola FromAddress) ConfirmationMail string Adres email na który zostanie dostarczona informacja o zakończeniu wysyłki kampanii. Pole opcjonalne. HtmlFromWebSiteUrl string Adres strony www, której treść zostanie automatycznie zaimportowana jako szablon maila. Jedno z dwóch pól musi być podane: HtmlFromWebSiteUrl albo HtmlContent. HtmlContent string Treść HTML wiadomości email. Jedno z dwóch pól musi być podane: HtmlFromWebSiteUrl albo HtmlContent. EmbedImages Boolean Obrazki dołączone do treści emaila. Pole opcjonalne, w przypadku braku system ustawi na true. TextContent string Treść tekstowa (TEXT) wiadomości email. Pole opcjonalne. GroupId string Identyfikator grupy kontaktów - jeżeli wysyłka ma się opierać na kontaktach wprowadzonych do systemu Redlink.pl. Jedno z trzech pól musi zostać podane : GroupId albo ContactId albo Mails. ContactIds ArrayOfString Lista identyfikatorów kontaktów (z systemu Redlink.pl), na które ma zostać wysłana wiadomość email. Mails ArrayOfString Lista adresów email, na które ma zostać wysłana wiadomość email. Można podać maksymalnie 5000 adresów email w jednej kampanii. TrackLinks Boolean Śledzenie linków - wszystkich znalezionych w treści HTML. Pole opcjonalne, w przypadku braku system ustawi na false. GoogleAnalytics Boolean Integracja z Google Analytics. Działa tylko w przypadku wybrania śledzenia linków (TrackLinks). Pole opcjonalne, w przypadku braku system ustawi na false. ScheduleTime datetime Czas wysyłki kampanii (może być odłożony w przyszłości). Pole opcjonalne, w przypadku braku system ustawi czas na aktualny. - 28 -
Analogicznie jak dla faxów, wysyłkę maili można oprzeć na wcześniej utworzonych kontaktach lub bezpośrednio podać listę adresów email. Definiując dane kampanii mailowej można korzystać ze znaczników personalizujących, analogicznie jak w Panelu Redlink.pl. Znaczniki można umieszczać w zmiennych obiektu MailCampaignData takich jak: Subject, TextContent, HtmlContent (bądź na stronie podanej w HtmlFromWebSiteUrl). W przypadku adresowania kampanii do kontaktów istniejących już systemie Redlink.pl - a więc zdefiniowania zmiennej GroupId albo ContactIds, do dyspozycji są wszystkie znaczniki personalizujące dostępne w Panelu (m.in.: ##Kontakt_Imię##, ##Kontakt_Nazwisko##, ##Kontakt_Email##, ##Kontakt_Adres## itp. oraz ##Link_Rezygnacji## i ##Link_Email_W_Nowym_Oknie## ) Natomiast w przypadku zdefiniowania zmiennej Mails możliwe jest wykorzystanie znacznika ##Kontakt_Email## (gdyż znany i podany zostaje tylko adres email odbiorcy) oraz ##Link_Rezygnacji## i ##Link_Email_W_Nowym_Oknie##. Użycie w treści HTML znacznika ##Link_Rezygnacji## jest konieczne tylko gdy w Panelu Redlink.pl (Ustawienia -> Ustawienia email) została zadeklarowana chęć korzystania z własnego linka rezygnacji (rezygnacja ze stopki Redlink). Typ MailSendResult opisujący rezultat pojedynczej wysyłki. ContactId string Identyfikator kontaktu - jeżeli był podany (puste w przypadku utworzenia kampanii z parametrem Mails tablica adresów). Mail string Adres email, na który został wysłany mail. ResultCode string Kod rezultatu: OK, HardBounce, SoftBounce, AutoResponder, Unsubscribe, Transient itp. (patrz dokumentacja statusów kampanii). Rezultat może się zmieniać w miarę upływu czasu. Email prawidłowo wysłany przez serwer SMTP Redlink.pl otrzymuje status OK. Z biegiem czasu serwer może otrzymać informacje (tzw. odbitkę ) od serwera pocztowego adresata o potencjalnym problemie (np. nie istnieniu adresu email, na który wiadomość została wysłana tzw. HardBounce). Wówczas rezultat zostanie zaktualizowany. Czas otrzymania odbitki jest czynnikiem zewnętrznym. ResultDetails string Szczegóły rezultatu (komentarz). Finished Boolean True jeżeli wysyłka dla tego kontaktu/adresu została zakończona. ReadReported Boolean True oznacza, że mail na pewno został przeczytany. Natomiast jeżeli false, a wynikiem wysyłki (ResultCode) jest status OK, to prawdopodobnie mail także został przeczytany, ale klient blokuje potwierdzenie tego faktu. Typ LinkClick opisujący poszczególne kliknięcia w śledzone linki. Link string Link który został kliknięty. ContactId string Identyfikator kontaktu, który kliknął link (puste w przypadku utworzenia kampanii z parametrem Mails tablica adresów). Email string Adres email adresata, który kliknął w link. LastClickDate datetime Data ostatniego kliknięcia przez danego adresata. - 29 -