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

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

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

- Агент ThunderPhone и [API-ключ](/ru/guides/api-keys) организации.
- Twilio Programmable Voice и место для обслуживания TwiML и обработчика
  `referUrl`: собственный сервер или TwiML Bin и Twilio Function. Flex
  необязателен.

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

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

```bash
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-адресов](/ru/guides/sip-addresses).

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

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

```xml
<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](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` удерживает звонящего на линии, пока не ответит новый адресат,
  поэтому при неудачном переводе можно использовать резервный вариант.

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

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

Агент выполняет перевод с помощью `REFER`, адрес перевода которого содержит
идентификатор и намерение передачи. Добавьте этот номер перевода (см.
[Добавление номера перевода](/ru/guides/contact-centers/overview)
и [Заголовки внутри адреса перевода](/ru/guides/call-transfers)):

```json
{
  "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`:

```js
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 в переменных окружения функции. Другие поля см. в разделе
[Поиск переданного вызова](/api-reference/calls#look-up-a-handed-off-call).

## Проверьте

Позвоните на номер 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>`, как указано выше.
