ThunderPhone v3 уже доступен.Самостоятельный запуск — от 2 ¢/мин.Читать анонс

Contact centers

Подключение из Twilio

Направляйте звонки Twilio голосовому агенту ThunderPhone по SIP с помощью CallSid и возвращайте их через referUrl с передачей в адресе перевода.

Ваш TwiML набирает SIP-адрес агента, передавая CallSid звонка в заголовке. Когда звонящему нужен человек, агент отправляет SIP REFER, Twilio передаёт адрес перевода с данными передачи в ваш обработчик referUrl, а TwiML, который возвращает обработчик, определяет, куда будет направлен звонящий, например в очередь Flex.

Прежде чем начать

  • Агент ThunderPhone и API-ключ организации.
  • Twilio Programmable Voice и место для обслуживания TwiML и обработчика referUrl: собственный сервер или TwiML Bin и Twilio Function. Flex необязателен.

1. Создайте конечную точку SIP

<Sip> Twilio принимает имя пользователя и пароль, поэтому используйте стандартную конечную точку:

curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Twilio"}'

Сразу сохраните password из ответа: он отображается только один раз. Чтобы также принимать звонки только от Twilio, см. Ограничение исходных IP-адресов.

2. Направляйте звонки с контекстом

Верните этот TwiML для звонка, который нужно передать агенту:

<Response>
  <Dial answerOnBridge="true" referUrl="https://YOUR_SERVER/thunderphone-refer">
    <Sip username="tp409667538f83" password="YOUR_ENDPOINT_PASSWORD">sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls?X-Call-ID={{CallSid}}</Sip>
  </Dial>
</Response>
  • ;transport=tls важен: без него Twilio использует UDP.
  • X-Call-ID передаёт CallSid. Twilio не документирует собственный заголовок идентификатора звонка, поэтому добавьте этот: ThunderPhone сохраняет его как external_call_id звонка. {{CallSid}} работает в TwiML Bin; на собственном сервере укажите CallSid входящего запроса.
  • Добавьте больше контекста таким же способом, например &amp;X-Account-Id=12345. Внутри TwiML записывайте & как &amp;, поскольку отдельный & недопустим в XML. Каждый параметр поступает в промпт как переменная, здесь {{sip_x_account_id}}. Twilio поддерживает заголовки x- и User-to-User с процентным кодированием, если вся URI содержит менее 255 символов, а заголовки — менее 1 024.
  • referUrl позволяет Twilio принять REFER агента; без него перевод завершается ошибкой 13802. answerOnBridge="true" удерживает звонящего на линии, пока не ответит новый адресат, поэтому при неудачном переводе можно использовать резервный вариант.

Виджет Studio Подключить звонок к не документирует пользовательские заголовки или referUrl, поэтому из Studio передавайте звонок этому TwiML, например с помощью виджета Перенаправление TwiML.

3. Получите вызов обратно

Агент выполняет перевод с помощью REFER, адрес перевода которого содержит идентификатор и намерение передачи. Добавьте этот номер перевода (см. Добавление номера перевода и Заголовки внутри адреса перевода):

{
  "name": "Twilio support",
  "number": "sip:support@acme.sip.twilio.com",
  "headers": {"X-Handoff-Id": "{{handoff_id}}", "X-Handoff-Intent": "{{handoff_intent}}"},
  "headers_in_uri": true
}

Twilio отправляет весь адрес в ваш referUrl как ReferTransferTarget, например <sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>. Ваш обработчик извлекает из него заголовки и возвращает TwiML, определяющий, куда звонящий будет направлен дальше. Пользовательская часть адреса (support) выбирается вами, поэтому можно добавить по одному номеру перевода для каждого назначения и маршрутизировать по нему.

Эта функция Twilio помещает звонящего в очередь Flex с передачей в качестве атрибутов задачи и получает сводку по идентификатору передачи. Поиск выполняется в функции, поскольку виджет HTTP Request в Studio не может отправлять заголовок Authorization:

exports.handler = async (context, event, callback) => {
  const target = (event.ReferTransferTarget || "").replace(/^<|>$/g, "");
  const params = new URLSearchParams(target.split("?")[1] || "");
  const handoffId = params.get("X-Handoff-Id") || "";
  const attributes = { handoff_id: handoffId, intent: params.get("X-Handoff-Intent") || "" };
 
  if (handoffId) {
    const response = await fetch(
      "https://api.thunderphone.com/v1/calls/handoff?handoff_id=" + encodeURIComponent(handoffId),
      { headers: { Authorization: "Bearer " + context.THUNDERPHONE_API_KEY } }
    );
    if (response.ok) {
      const call = await response.json();
      attributes.summary = (call.handoff && call.handoff.summary) || "";
    }
  }
 
  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.enqueue({ workflowSid: context.FLEX_WORKFLOW_SID }).task({}, JSON.stringify(attributes));
  callback(null, twiml);
};

Храните ключ API в переменных окружения функции. Другие поля см. в разделе Поиск переданного вызова.

Проверьте

Позвоните на номер Twilio, который возвращает указанный выше TwiML, попросите агента соединить с человеком и убедитесь, что ваш обработчик referUrl получает ReferTransferTarget с обоими заголовками и что звонящий попадает в очередь. Затем откройте вызов через GET /v1/calls/{call_id}: значением external_call_id должен быть CallSid.

Ограничения

  • Twilio ограничивает Refer-To 256 символами. ThunderPhone сохраняет адрес длиной до 254 символов и исключает заголовок, который не помещается, поэтому используйте короткие имена и значения заголовков.
  • Twilio не документирует чтение заголовков в BYE, поэтому возврат не может передать информацию о передаче обратно в Twilio. Используйте REFER, как указано выше.
  • Twilio не принимает REFER для вызова, подключённого через <Conference> или <Queue>, поэтому набирайте агента через <Dial><Sip>, как указано выше.