SMS API ръководство за програмисти

Започвате ли работа с SMSAPI API? Прочетете първата част от ръководството за програмисти и нека ви преведем през пет лесни стъпки към първия ви SMS, изпратен чрез API. Както подсказва и името, SMSAPI е създадена от програмисти за програмисти. Нашите основатели искаха да подчертаят, че създадената от тях платформа е специално за IT потребители.

Тази статия е предназначена за всички, които се борят с първите стъпки. Ще ви покажа как да използвате нашия API. Започнете, като посочите най-важните и основни неща, които трябва да направите: изпратете първия си SMS чрез API.

Освен нашия изключително стабилен и надежден API имаме и уеб базирана версия. Порталът за клиенти се използва от потребители, които не владеят програмиране. Повечето от тях дори не осъзнават значението на втората част от името ни – те просто искат да изпращат групови SMS съобщения до клиентите си.

Въпреки това нашият API постоянно се надгражда, модернизира и разширява. По-важното е, че се използва активно от нашите клиенти като iQueue, Insly и ProTrainUp. Искаме да помогнем на компании, които се нуждаят от ефективно, бързо и надеждно комуникационно решение, да започнат да използват API.

Напълно сме наясно, че решението „Нека изберем SMSAPI и техния API за изпращане на текстови съобщения“ вероятно е било взето от друг отдел (ако вашата компания има такава структура). В края на краищата разработчикът ще трябва да влезе в своето IDE, да си направи кафе и да изрови всичко това. Затова нека ви помогнем.


Стъпка 1: създайте и верифицирайте SMSAPI акаунт

Излишно е да казваме, че това е първата и най-важна стъпка, за да започнете работата си – създаване на акаунт. Разбира се, ако вече имате такъв, върху който да работите, можете да прескочите напред или да създадете под-акаунт за себе си. Не забравяйте да го заредите, за да имате точки за извършване на тестове.

Стъпка 2: добавете име на изпращач

Името на изпращача на SMS се показва в телефона на получателя на мястото на податея. Изглежда като снимката вдясно. Той може да има до 11 знака и трябва да представлява марката, изпратила съобщението. Затова изберете име, което ще бъде лесно разпознаваемо като част от комуникацията на вашата компания.

По подразбиране всички съобщения, изпратени от нов SMSAPI акаунт, са маркирани като „тест“ и това е напълно достатъчно за тестове. Но ако искате да работите с вашето име, трябва да завършите процеса на регистрация и активиране. Можете да го направите в клиентския портал на SMSAPI и то изключително лесно. Изгледайте краткото ни видео с инструкции по-долу:

Стъпка 3: Решете дали ще използвате библиотека или API

Това е първият важен избор, който трябва да направите. От една страна, има библиотеки, създадени от SMSAPI. Те са достъпни на няколко популярни езика и можете да ги изтеглите от GitHub.

От друга страна, можете да се свържете директно с API, без никаква библиотека. Процесът е подробно описан с някои примери в нашата документация под формата на OpenAPI с помощта на популярния инструмент Swagger.

Изборът зависи изцяло от вас, вашите предпочитания и вашите цели. Всички библиотеки ще ви позволят да изпращате текстови съобщения, за да работите с нашата база данни с контакти. В същото време не всички от тях поддържат виртуални мобилни номера (специални номера, които ви позволяват да получавате съобщения от клиентите си), но ние ще разгледаме това в една от следващите статии.

Ако търсите бърза и лесна интеграция, препоръчваме да използвате някоя от готовите библиотеки, ако приемем, че се развивате на един от наличните езици. Това ще улесни и ускори работата ви.

Но! Ако планирате да правите нещо по-напреднало от инструментите, предоставени от библиотеката, или предпочитате да не използвате Fluent API (в примера на JS библиотеката) и искате да имате по-голям контрол върху интеграцията, трябва да знаете, че свързването с API директно е също толкова жизнеспособен избор.

Стъпка 4: генериране на ключ за оторизация

Това е друго действие, което изисква да влезете в портала за клиенти. Отидете на раздела, показан по-долу.

Управление на API токените в клиентския портал на SMSAPI

След това кликнете върху бутона „Генериране на токен за достъп“. Ще се покаже прозорец, където можете да ограничите достъпа на маркера, за да отговаря на вашите нужди. Като се има предвид минимализирането и сигурността на достъпа до данни, изборът на текстови съобщения (SMS) ще бъде достатъчен – можете да изключите останалите.

Когато приключите, кликнете върху „Генериране на токен“, след което ще видите нов прозорец с току-що генерирания ви токен.

Обърнете внимание!

Поради съображения за сигурност, повече няма да ви покажем пълния знак. Така че, най-добре е да го поставите в кода веднага (или още по-добре директно в конфигурацията). Ако затворите изскачащия прозорец, преди да го копирате, ще трябва да генерирате нов знак.

Стъпка 5: искане за тестване на API

Остава само да изпратите първото си текстово съобщение чрез API на SMSAPI! За да направите това, използвайте кода по -долу. В случай на проблеми, нашата документация е там, за да ви помогне.

<?php

/** URL address of SMSAPI API, @see https://www.smsapi.com/docs/#url-adresses */

$smsApiUrl = ‘https://api.smsapi.com’;

/** OAuth autorization token, @see https://ssl.smsapi.com/react/oauth/manage */

$smsApiToken = ‘token_oauth’;

/** sender name, @see https://ssl.smsapi.com/sms_settings/sendernames */

$from = ‘test’;

/** recipient list, separated by comma */

$to = ‘XXXXXXXXX’;

/** message body */

$message = ‘Hello world!’;

/** answer format */

$format = ‘json’;

$httpClient = curl_init();

curl_setopt($httpClient, CURLOPT_URL, $smsApiUrl . ‘/sms.do’);

curl_setopt($httpClient, CURLOPT_POST, true);

curl_setopt($httpClient, CURLOPT_POSTFIELDS, [

    ‘to’ => $to,

    ‘from’ => $from,

    ‘message’ => $message,

    ‘format’ => $format,

]);

curl_setopt($httpClient, CURLOPT_RETURNTRANSFER, true);

curl_setopt($httpClient, CURLOPT_HTTPHEADER, [

    ‘Authorization: Bearer ‘ . $smsApiToken

]);

$apiResponse = curl_exec($httpClient);

curl_close($httpClient);

echo $apiResponse . PHP_EOL;

?>

Това е код, който ще изпрати първото ви съобщение до избраните номера на получатели. Вероятно е най-добре да промените номера на вашия, за да получите текста. 🙂 Направете го в променливата $ to. О, и трябва да поставите маркера си OAuth в променливата $ smsApiToken.

Трябва да обърнете допълнително внимание на номера на получателя в променливата $ to. Той трябва да бъде предшестван с код на държава, точно като „359123456789 ″ -„ 359 “е код на държава, а„ 123456789 “е примерен телефонен номер. Ние сме международна компания, затова се нуждаем от кода, за да знаем до коя държава трябва да достигне съобщението.

Остава само изпълнението на кода в PHP интерпретатора. Направете го, като запазите кода като файл testSms.php на вашия компютър с присъстващ PHP интерпретатор. Всички версии> = 5.4 трябва да изпълняват скрипта добре с командата (може да се наложи да настроите командата към вашата конкретна среда, ако нямате PHP във вашия $ PATH или вашият PHP изпълним файл е наречен по различен начин):

php testSms.php

Ако всичко върви гладко, трябва да получите известие за успех във формат JSON, изглеждащ по следния начин:

{„count“:1,“list“:[{„id“:“566275XXXXX“,“points“:0.14,“number“:“48XXXXXXXXX“,“date_sent“:1603356627,“submitted_number“:“XXXXXXXXX“,“status“:“QUEUE“,“error“:null,“idx“:null,“parts“:1}]}

Не след дълго трябва да получите първия си SMS!


Най-често срещани грешки:

Ами ако тестът не е приключил успешно? API ще ви предостави код за грешка, който ще ви помогне да идентифицирате причината за неизправността. Всички грешки са обяснени в документацията. Най-често срещаните са:

  • Грешка 101: невалидна информация за оторизация – невалидни данни за маркер или връзка със сървъра, напр. на api.com.pl вместо на api.smsapi.bg;
  • Грешка 14: грешно име на подател – грешно или неактивно име на изпращач на SMS; проверете имената на подателите в портала за клиенти;
  • Грешка 11: съобщението е твърде дълго или няма съобщение, или параметър: nounicode е зададен и се използват специални знаци (включително полски) – опитвате се да изпратите съобщение по-дълго от лимита, зададен в конфигурацията на акаунта – не забравяйте това съобщение със знаци извън Unicode има по-ниска граница. Както обикновено, ще намерите повече информация в документацията;
  • Грешка 13: липса на валидни телефонни номера (невалидни или в черния списък) – доставката е неуспешна поради неактивните или блокирани номера; проверете дали въведените числа са валидни и дали няма допълнителни символи;
  • Грешка 103: недостатъчни кредити по сметката ви – няма достатъчно точки по сметката или подсметката;


Няколко грешки не се показват чрез SMSAPI съобщение за грешка (и те няма да присъстват в регистрационните файлове). Това е така, защото те са възникнали преди връзката с API на SMSAPI да бъде установена. Най-често срещаните са:

  • Връзка с грешен адрес – правилният адрес може да бъде намерен в нашата документация;
  • Връзка, използваща версия на протокола TLS по-ниска от 1.2 – не поддържаме по-стари версии на протокола TLS, защото те са амортизирани и недостатъчно сигурни. Трябва да проверите TLS версията на вашата система (среда) и вероятно да актуализирате цялата си среда или нейната част;
  • Връзката, блокирана от защитна стена от страна на клиента, означава, че връзката е била блокирана някъде между вашата машина и нашия API; трябва да проверите системата си или да говорите с мрежовия администратор. Проблемите рядко възникват на компютрите на разработчиците (ако е така, дори няма да можете да прочетете тази статия), но това е възможен сценарий в изолирани мрежи, работещи в сървърни центрове.

Има още нещо, което може да ви попречи да получите този SMS на телефона си. Някои имена на податели са блокирани в определени държави. За съжаление, името на нашия подател по подразбиране „тест“ също е блокирано в някои региони, като Великобритания.

Много местни ограничения (наложени от държава или дори от SMS доставчик) регулират управлението на името на подателя. Ето защо трябва да работим за всеки отделен случай, като обикновено попълваме някаква кратка документация, ако искаме да използваме специфични за марката имена на податели. Така че, ако се борите с получаването на SMS, въпреки че API ви изпраща съобщение за успех, свържете се с нашия специалист по поддръжка за повече информация и той ще ви съдейства възможно най-бързо.


Какво следва? Нашият API за SMSAPI има много приложения. Можете да управлявате данните за контакти във вашия SMSAPI акаунт, да добавяте параметри към телата на съобщенията или да променяте настройките на акаунта. Освен това ви позволява да използвате функцията за обратно отговаряне, необходима при получаване на съобщения от вашите клиенти. Така че, следете ни. Ще обясня всичко стъпка по стъпка в предстоящите статии.