====== Краткое пошаговое руководство по работе с сервисом зачитывания текстовых сообщений ======

В качестве клиента используем бесплатную программу [[https://www.soapui.org|SOAP UI]], но принцип работы сохраняется и при использовании других продуктов. В том числе и при разработке ПО на .NET ([[https://en.wikipedia.org/wiki/SOAP#History|Microsoft придумала стандарт SOAP]] и их средства как никакие другие подходят для этого). Программа существует под все популярные платформы и не имеет ограничений использования.\\
\\
Руководство по программе можно найти [[https://www.soapui.org/soap-and-wsdl/getting-started.html|на официальном сайте]]\\
\\
В SOAP UI создаём новый проект и в качестве Initial WSDL используем ссылку из [[products:kmis:project_documentation:server|документации]]: [[http://kmis.callbox.biz/?wsdl]]\\
\\
В этот момент SOAP UI (как и библиотека .NET) выгрузит из WSDL все приложения. Их три:
  - //get_report// - получение статистики
  - //notification// - оповещение абонента
  - //upload_audio// - загрузка файла на сервис

Также программа выгрузит все методы для всех приложений. На текущий момент в каждом приложении 1 метод.\\
\\
При переходе к редактированию метода //Request// приложения //notification// откроется полный текст запроса с комментариями к нему:
<code>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kmis="kmis.services" xmlns:ser="services.custom_types">
   <soapenv:Header/>
   <soapenv:Body>
      <kmis:notification>
         <kmis:request_data>
            <ser:customer_id>?</ser:customer_id>
            <!--Optional:-->
            <ser:sms_notifications>
               <!--1 or more repetitions:-->
               <ser:UserDataSMS>
                  <ser:date_begin>?</ser:date_begin>
                  <ser:date_end>?</ser:date_end>
                  <!--Optional:-->
                  <ser:start_time>?</ser:start_time>
                  <!--Optional:-->
                  <ser:end_time>?</ser:end_time>
                  <ser:recipients_data>
                     <!--1 or more repetitions:-->
                     <ser:RecipientData>
                        <ser:request_id>?</ser:request_id>
                        <ser:recipient_phone>?</ser:recipient_phone>
                        <ser:is_personalized>?</ser:is_personalized>
                        <!--Optional:-->
                        <ser:template_parameters>
                           <!--1 or more repetitions:-->
                           <ser:TemplateParameter>
                              <ser:key>?</ser:key>
                              <ser:value>?</ser:value>
                           </ser:TemplateParameter>
                        </ser:template_parameters>
                     </ser:RecipientData>
                  </ser:recipients_data>
                  <ser:message_template>?</ser:message_template>
                  <!--Optional:-->
                  <ser:attempt_count>?</ser:attempt_count>
               </ser:UserDataSMS>
            </ser:sms_notifications>
            <!--Optional:-->
            <ser:ts_notifications>
               <!--1 or more repetitions:-->
               <ser:UserDataReadText>
                  <ser:date_begin>?</ser:date_begin>
                  <ser:date_end>?</ser:date_end>
                  <!--Optional:-->
                  <ser:start_time>?</ser:start_time>
                  <!--Optional:-->
                  <ser:end_time>?</ser:end_time>
                  <ser:recipients_data>
                     <!--1 or more repetitions:-->
                     <ser:RecipientData>
                        <ser:request_id>?</ser:request_id>
                        <ser:recipient_phone>?</ser:recipient_phone>
                        <ser:is_personalized>?</ser:is_personalized>
                        <!--Optional:-->
                        <ser:template_parameters>
                           <!--1 or more repetitions:-->
                           <ser:TemplateParameter>
                              <ser:key>?</ser:key>
                              <ser:value>?</ser:value>
                           </ser:TemplateParameter>
                        </ser:template_parameters>
                     </ser:RecipientData>
                  </ser:recipients_data>
                  <ser:message_template>?</ser:message_template>
                  <!--Optional:-->
                  <ser:attempt_count>?</ser:attempt_count>
               </ser:UserDataReadText>
            </ser:ts_notifications>
            <!--Optional:-->
            <ser:audio_notifications>
               <!--1 or more repetitions:-->
               <ser:UserDataAudio>
                  <ser:date_begin>?</ser:date_begin>
                  <ser:date_end>?</ser:date_end>
                  <!--Optional:-->
                  <ser:start_time>?</ser:start_time>
                  <!--Optional:-->
                  <ser:end_time>?</ser:end_time>
                  <ser:recipients_data>
                     <!--1 or more repetitions:-->
                     <ser:RecipientBaseData>
                        <ser:request_id>?</ser:request_id>
                        <ser:recipient_phone>?</ser:recipient_phone>
                     </ser:RecipientBaseData>
                  </ser:recipients_data>
                  <ser:audio_record_id>?</ser:audio_record_id>
                  <!--Optional:-->
                  <ser:attempt_count>?</ser:attempt_count>
               </ser:UserDataAudio>
            </ser:audio_notifications>
         </kmis:request_data>
      </kmis:notification>
   </soapenv:Body>
</soapenv:Envelope>
</code>
Вопросительные знаки требуют ввода данных.\\
\\
Метод описывает сразу три возможных оповещения: посылка СМС (раздел sms_notifications), звонок абоненту с зачитыванием текста (ts_notifications) и звонок абоненту с проигрыванием файла (audio_notifications). В запросе должен быть использовано хотя бы одно оповещение. При этом, можно в одном запросе рассылать оповещения всех типов разным абонентам.\\
\\
Нас интересует зачитывание текста абонента. Для его создания удаляем из запроса секции sms_notifications и audio_notification и приводим запрос к виду:
<code>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kmis="kmis.services" xmlns:ser="services.custom_types">
   <soapenv:Header/>
   <soapenv:Body>
      <kmis:notification>
         <kmis:request_data>
            <ser:customer_id>?</ser:customer_id>
            <ser:ts_notifications>
               <!--1 or more repetitions:-->
               <ser:UserDataReadText>
                  <ser:recipients_data>
                     <!--1 or more repetitions:-->
                     <ser:RecipientData>
                        <ser:request_id>?</ser:request_id>
                        <ser:recipient_phone>?</ser:recipient_phone>
                        <ser:is_personalized>?</ser:is_personalized>
                        <!--Optional:-->
                        <ser:template_parameters>
                           <!--1 or more repetitions:-->
                           <ser:TemplateParameter>
                              <ser:key>?</ser:key>
                              <ser:value>?</ser:value>
                           </ser:TemplateParameter>
                        </ser:template_parameters>
                     </ser:RecipientData>
                  </ser:recipients_data>
                  <ser:date_begin>?</ser:date_begin>
                  <ser:date_end>?</ser:date_end>
                  <!--Optional:-->
                  <ser:start_time>?</ser:start_time>
                  <!--Optional:-->
                  <ser:end_time>?</ser:end_time>
                  <ser:message_template>?</ser:message_template>
                  <!--Optional:-->
                  <ser:attempt_count>?</ser:attempt_count>
               </ser:UserDataReadText>
            </ser:ts_notifications>
         </kmis:request_data>
      </kmis:notification>
   </soapenv:Body>
</soapenv:Envelope>
</code>

Далее необходимо построчно заполнить данный запрос.\\
Первая строка с вопросительным знаком идентифицирует пользователя системы:
<code><ser:customer_id>?</ser:customer_id></code>
Вместо вопросительного знака необходимо в данную строку подставить UUID, выданный администратором системы. Пример корректного заполнения:
<code><ser:customer_id>394ffb3b-20f5-4046-b6b2-758103698fe7</ser:customer_id></code>
Вторая строка с вопросительным знаком идентифицирует запрос.
<code><ser:request_id>?</ser:request_id></code>
В данную строку необходимо сгенерить и подставить UUID. В случае дублирование UUID (некорректная генерация) сервер выдаст сообщение об ошибке. Пример корректного заполнения:
<code><ser:request_id>edeb4385-a7c5-4b1e-862c-bbf4b8b73abe</ser:request_id></code>
Следующая строка с вопросительным знаком, требующая заполнения определяет номер телефона пользователя, на который будет совершён звонок и будет зачитано сообщение. Номер принимается в формате Е164. В качестве исключения код страны +7 может быть заменён на 8. При этом в данном случае в системе номер будет преобразован в формат Е164 и отчётная информация будет выводится именно по такому номеру.
<code><ser:recipient_phone>?</ser:recipient_phone></code>
Пример корректного заполнения:
<code><ser:recipient_phone>+77778897158</ser:recipient_phone></code>
Следующая строка, требующая заполнения определяет является ли рассылка персонализированной или нет.
<code><ser:is_personalized>?</ser:is_personalized></code>
Данное поле обязательно для заполнения (комментарий Optional перед ним в WSDL введён на момент отладки системы). В случае, если флаг установлен в False сообщение отсылается в том виде, в каком оно передано в запросе. В случае, если флаг установлен в True система воспринимает передаваемый текст как шаблон и ищет в запросе поля для его заполнения. Корректно заполнение поля для зачитывания не адресного сообщения:
<code><ser:is_personalized>false</ser:is_personalized></code>
Следующий блок используется для создания шаблонных сообщений и в данном примере не используется. Более подробно этот блок описан в [[servers:kmis:server|документации к системе]]
<code>
                        <!--Optional:-->
                        <ser:template_parameters>
                           <!--1 or more repetitions:-->
                           <ser:TemplateParameter>
                              <ser:key>?</ser:key>
                              <ser:value>?</ser:value>
                           </ser:TemplateParameter>
                        </ser:template_parameters>
</code>
В нашем примере он должен быть удалён.\\
Следующая строка, требующая заполнения определяет дату начала начала обзвона абонента.
<code><ser:date_begin>?</ser:date_begin></code>
Дата указывается в формате YYYY-MM-DD и может быть произвольной. При этом хотя бы один день из диапазона дат должен быть в будущем. Пример корректного заполнения (показана дата в прошлом на момент написания статьи):
<ser:date_begin>2017-08-01</ser:date_begin>
Следующая строка, требующая заполнения определяет дату окончания обзвона абонента.
<code><ser:date_end>?</ser:date_end></code>
Дата указывается в формате YYYY-MM-DD и может быть произвольной. При этом хотя бы один день из диапазона дат должен быть в будущем. Пример корректного заполнения:
<code><ser:date_end>2017-08-03</ser:date_end></code>
Следующие две строки, требующие заполнения определяют время начала и время окончания обзвона абонента. Временной интервал применяется к одним суткам. То есть, например, если нам необходимо пытаться дозвониться до абонента каждый день только с полудня и до конца рабочего дня то в данных полях можно указать 12:00:00 и 17:00:00 и во вне этого интервала система не будет звонить абонентам из данного запроса.
<code>
<ser:start_time>?</ser:start_time>
<ser:end_time>?</ser:end_time>
</code>
При этом если время начала больше чем время окончания (например, с 18:00:00 до 09:00:00) то система проверяет что диапазон дат содержит несколько дней и будет пытаться дозвониться до абонента в ночное время.\\
Указание временного диапазона необязательно. В случае, если временной диапазон не указан, то система будет пытаться дозвониться до абонента с 9:00:00 до 17:00:00. Пример корректного заполнения:
<code>
<ser:start_time>00:00:00</ser:start_time>
<ser:end_time>23:59:59</ser:end_time>
</code>
Следующая строка содержит текст непосредственно зачитываемого сообщения
<code><ser:message_template>?</ser:message_template></code>
В случае, если указан флаг персональных сообщений данная строка воспринимается как шаблон. Описание шаблона смотрите в полной документации к работе сервера. Пример корректного заполнения:
<code><ser:message_template>Здравствуйте, Вам звонят из городской поликлиники города Караганда по вопросу прохождения обследования</ser:message_template></code>
<note important>Система поддерживает зачитывание сообщений только на русском языке!</note>
Следующая строка определяет количество попыток дозвона до абонента. Система считает что попытка дозвона до абонента была неудачной если абонент не поднял трубку либо если продолжительность зачитывания сообщения была меньше 5 секунд (то есть абонент не дослушал наше сообщение до конца и бросил трубку). В таком случае через 30 минут система предпримет следующую попытку дозвона до абонента. Временной интервал второй (и последующих) попытки может больше если в момент наступления времени повтора все доступные телефонные каналы для данного клиента заняты.
<code><ser:attempt_count>?</ser:attempt_count></code>
Параметр может принимать любое целочисленное значение от 1 до 65535. Указание параметра не обязательно. В случае, если параметр не указан система предпримет одну попытку доставки сообщения. Пример корректного заполнения:
<code><ser:attempt_count>3</ser:attempt_count></code>
Итого, с учётом всех необязательных полей простейшей запрос для звонка абоненту с зачитыванием текста будет иметь следующий вид:
<code>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kmis="kmis.services" xmlns:ser="services.custom_types">
   <soapenv:Header/>
   <soapenv:Body>
      <kmis:notification>
         <kmis:request_data>
            <ser:customer_id>00c0bfb0-09b5-4bcc-a5da-abc5c7737f35</ser:customer_id>
            <!--Optional:-->
             <ser:ts_notifications>
               <!--1 or more repetitions:-->
               <ser:UserDataReadText>
                  <ser:recipients_data>
                     <!--1 or more repetitions:-->
                     <ser:RecipientData>
                        <ser:request_id>8e10b8d5-0f5c-4850-ad8e-7d21f1ea7ed8</ser:request_id>
                        <ser:recipient_phone>+77212921006</ser:recipient_phone>
                        <ser:is_personalized>false</ser:is_personalized>
                      </ser:RecipientData>
                  </ser:recipients_data>
                  <ser:date_begin>2017-08-01</ser:date_begin>
                  <ser:date_end>2017-08-31</ser:date_end>
                  <ser:message_template>Здравствуйте, Вам звонят из городской поликлиники города Караганда по вопросу прохождения обследования</ser:message_template>
                  <!--Optional:-->
                  <ser:attempt_count>3</ser:attempt_count>
               </ser:UserDataReadText>
            </ser:ts_notifications>
         </kmis:request_data>
      </kmis:notification>
   </soapenv:Body>
</soapenv:Envelope>
</code>