Webitel API

Примеры запросов на Webitel API

1. Дайлеры.

1.1. Загрузка абонентов в дайлер.

https://swagger.webitel.com/#/MemberService/MemberService_CreateMemberBulk

Важно

  • CRM должен сохранять идентификатор загруженного абонента для дальнейшего использования, например, при отмене прозвона.
  • Для отображения названия корзины оператору при входящем звонке в массиве varialbles обязательно нужно передавать название корзины(bucket_name).
  • Для открытия карточки клиента в CRM по ссылке в массиве varialbles обязательно нужно передавать полную ссылку на карточку этого клиента. Название переменной - {link}.


Create member
{
  "items": [ 									// массив абонентов (мемберов). Каждый отдельный объект – это отдельный абонент.
    {
      "agent": { 								// определяет привязку абонента к конкретному оператору, необязательно.
        "id": "${id}" 							// идентификатор оператора
      },
       "bucket": {  
        "id": "${id}" 							// идентификатор корзины. Применяется для привязки оператора и клиента. Предусматривается использование корзин для продуктов в рамках очереди для одной
страны.
      },
      "communications": [  						// в этом массиве передается номер/номера клиентов.           {
		  "description": "${description}",  	// описание способа связи.
          "destination": "${destination}", 		// номер абонента, обязательное.
          "display": "${display}", 				// номер, который будет отображаться абоненту во время звонка, необязательное.
          "priority": 0, 						// приоритет destination в рамках абонента. Когда в массиве communications есть несколько номеров, приоритет будет определять порядок их обзвона. Чем больше число, тем выше приоритет. Обязательное.
          "resource": {  						// определяет привязку абонента к конкретному ресурсу, с которого будет проводиться обзвон. Не обязательное.
            "id": "${id}"  						// идентификатор ресурса. См. "Получение списка ресурсов".
          },
          "type": {
            "id": "${id}"  						// идентификатор типа коммуникации из справочника Webitel, обязательное. Див. "Получение списка типов коммуникации".      
          }
        }
      ],
      "expire_at": "${expire_at}",  			// указывает время, когда удалить абонента с прозвона (Unix time)
      "min_offering_at": "${min_offering_at}",  // указывает время начала обзвона абонента. Timestamp во временной зоне UTC.
      "name": "${name}", 						// имя абонента, обязательное. 
      "priority": 0, 							// приоритет абонента в рамках очереди. Чем больше число, тем выше приоритет обзвона абонента.
      "timezone": {
        "id": "${id}"							// идентификатор временной зони (справочник на странице Webitel). См. "Получение списка временных зон"
      },
      "variables": {							// дополнительные переменные по клиенту, которые будут отображаться оператору при приеме звонка. 
        "additionalProp1": "${additionalProp1}",  
        "additionalProp2": "${additionalProp2}",
        "additionalProp3": "${additionalProp3}"
      }
    }
  ],
  "queue_id": "${queue_id}"						// идентификатор очереди, в которую загружаются абоненты. 
}

1.2. Получение списка временных зон.

https://swagger.webitel.com/#/CalendarService/CalendarService_SearchTimezones

1.3. Получение списка корзин.

https://swagger.webitel.com/#/BucketService/BucketService_SearchBucket

1.4. Получение списка типов коммуникации.

https://swagger.webitel.com/#/CommunicationTypeService/CommunicationTypeService_SearchCommunicationType

1.5. Отмена прозвона абонента дайлером.

https://swagger.webitel.com/#/MemberService/MemberService_PatchMember

Обязательные параметры:

  • идентификатор очереди дайлера;
  • идентификатор абонента в очереди.

Чтобы отменить прозвон абонента, нужно отправить запрос:

"stop_cause": "cancel"

Чтобы очистить предыдущий результат абонента в списке на прозвон, нужно отправить запрос:

"stop_cause": "null"  (или пустую строку)

Другие параметры заполнять не нужно.

2. Инициация ручного исходящего звонка из CRM (Click-to-call)

https://swagger.webitel.com/#/CallService/CallService_CreateCall

Для совершения исходящего звонка из CRM оператор должен иметь зарегистрированный SIP-телефон и token для выполнения запросов.

Create call
{
  "destination": "${agent_id}",			// номер назначения, обязательное.
  "from": {
    "extension": "${extension}"			// внутренний номер оператора, обязательное. См. "Получение списка операторов".
  },
  "params": {
    "disable_auto_answer": true,		// выключает автоподнятие трубки. Если передать параметр, то дополнительно оператору нужно будет принять у Workspace.
    "variables": { 						// дополнительные переменные по клиенту, которые могут использоваться для статистики.
      "additionalProp1": "${additionalProp1}",
      "additionalProp2": "${additionalProp2}",
      "additionalProp3": "${additionalProp3}"
    }
  }
}

3. Управление навыками операторов.

3.1. Получение списка операторов.

https://swagger.webitel.com/#/AgentService/AgentService_SearchAgent

3.2. Получение списка навыков Webitel.

https://swagger.webitel.com/#/SkillService/SkillService_SearchSkill

3.3. Получение навыков оператора.

https://swagger.webitel.com/#/AgentSkillService/AgentSkillService_SearchAgentSkill

Обязательные параметры:

  • идентификатор оператора.

3.4. Добавление навыка оператору.

https://swagger.webitel.com/#/AgentSkillService/AgentSkillService_CreateAgentSkill


Create Agent Skills
{
  "agent_id": "${agent_id}",	// идентификатор оператора. См. "Получение списка операторов"
  "capacity": 0,				// потенциал (уровень владения навыком). Возможные значения: 0-100
  "enabled": true,				// состояние навыка (он может быть включен/выключен)
  "skill": {
    "id": "${id}" 				// идентификатор навыка из справочника Webitel. См. "Получение списка навыков Webitel"
  }
}

3.5. Удаление навыка оператора.

https://swagger.webitel.com/#/AgentSkillService/AgentSkillService_DeleteAgentSkill

Обязательные параметры:

  • идентификатор оператора;
  • идентификатор навыка у оператора (См. "Получение навыков оператора")

3.6. Редактирование навыка оператора.

https://swagger.webitel.com/#/AgentSkillService/AgentSkillService_PatchAgentSkill

Обязательные параметры:

  • идентификатор оператора;
  • идентификатор навыка у оператора (См. "Получение навыков оператора")


Update Agent Skills
{
  "agent_id": "${agent_id}",	// идентификатор оператора
  "capacity": 0,   				// потенциал (уровень владения навыком). Возможные значения: 0-100
  "enabled": true, 				// состояние навыка (он может быть включен/выключен)  
  "id": "${id}",  				// идентификатор навыка оператора, который редактируется
  "skill": {
    "id": "${id}",  			// идентификатор навыка из справочника Webitel. См. "Получение списка навыков Webitel". Если заполнено, то поточный навык буде заменен.
  }
}

4. Постобработка.

4.1. Управление постобработкой. 

https://swagger.webitel.com/#/MemberService/MemberService_AttemptCallback

После завершения звонка оператор должен отправить статус обработки звонка (постобработка) з CRM в Webitel.

Возможные значения параметра status:

  • success - успешный дозвон. Повторной попытки дозвона не будет.
  • cancel - отмененный. Повторной попытки дозвона не будет.
  • любое другое переданное значение (если оно необходимо для статистики) будет считаться системой как статус abandoned.Будет повторная попытка дозвона согласно настройкам дайлера. 


Attempt Callback
{
  "agent_id": "${agent_id}",  					// идентификатор оператора
  "attempt_id": "${attempt_id}", 				// идентификатор попытки дозвона дайлера, по которой передается результат постобработки. Получается из RabbitMQ
  "description": "${description}",  			// комментарий, оставленный оператором при постобработке звонка
  "display": true, 								// отвечает за прикрепление номера отображения к этому абоненту
  "exclude_current_communication": true,  		// при значении true на текущий способ связи больше не будет звонков
  "expire_at": "${expire_at}", 					// указывает время, когда удалить абонента с прозвона (Unix time)
  "min_offering_at": "${min_offering_at}",		// timestamp значение конкретного времени перезвона дайлером в таймзоне UTC. Календарь дайлера имеет более высокий приоритет. Если указанное здесь время не входит в рабочее время дайлера, то повторная попытка будет сделана в рабочее время с наиболее высоким приоритетом.
  "status": "${status}", 						// статус попытки
  "variables": {
    "additionalProp1": "${additionalProp1}",
    "additionalProp2": "${additionalProp2}",
    "additionalProp3": "${additionalProp3}"
  }
}

5. Другое.

5.1. Получение списка очередей.

https://swagger.webitel.com/#/QueueService/QueueService_SearchQueue

6. История звонков.

6.1. Подключение к базе данных Webitel. 

В случае разворачивания Webitel On-Site, получение данных по звонкам и операторам возможно через подключение к БД Webitel (PostgreSQL 14).

Ссылка на описание структуры БД: Database SDK

6.2. Получение истории звонков. 

https://swagger.webitel.com/#/CallService/CallService_SearchHistoryCall


В базе данных в таблице storage.files сохраняется ссылка на запись разговора. 

id  |                        name                        |  size   | mime_type  |           properties            |              instance              |                 uuid                 | profile_id |  created_at   | removed | not_exists | domain_id
-----+----------------------------------------------------+---------+------------+---------------------------------+------------------------------------+--------------------------------------+------------+---------------+---------+------------+-----------
   1 | 8183fb7a-65d9-4d4c-bea2-3990f7e742d8_recordFile    |   17136 | audio/mpeg | {"directory""1/2021/5/17/18"} | storage-bsfob4a9rtdoue3mwanooxikpc | 8183fb7a-65d9-4d4c-bea2-3990f7e742d8 |            | 1621264377892 |         |

В поле uuid находится уникальный идентификатор звонка.

при помощи HTTP REST API существует возможность по UUID звонка получить список всех связанных файлов (не только записи разговоров (массив files)). 

Далее по идентификатору файла можно получить конкретный файл.

6.3. Получение записей по id файлов.

GET https://:WEBITEL_SERVER/api/storage/recordings/:FileID/stream?access_token=:TOKEN

:WEBITEL_SERVER - сервер Webitel.

Обязательные параметры:

  • :FileID - идентификатор файла, полученный с CallService_SearchHistoryCall;
  • :TOKEN - токен.

6.4. Поиск звонков по значению переменной.

GET https://:WEBITEL_SERVER/api/calls/history?page=1&size=10&number=110&variables[Company]=eb0b368c39305630464fa34c2af0e45f

:WEBITEL_SERVER - сервер Webitel.

Обязательные параметры:

  • number - номер телефона. Поиск осуществляется по from_number, to_number, destination;
  • Company - название переменной (метаданные);
  • page - страница, если много записей;
  • size - максимальное количество записей.