Open in
Подключение из 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входящего запроса.- Добавьте больше контекста таким же способом, например
&X-Account-Id=12345. Внутри TwiML записывайте&как&, поскольку отдельный&недопустим в 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-To256 символами. ThunderPhone сохраняет адрес длиной до 254 символов и исключает заголовок, который не помещается, поэтому используйте короткие имена и значения заголовков. - Twilio не документирует чтение заголовков в
BYE, поэтому возврат не может передать информацию о передаче обратно в Twilio. ИспользуйтеREFER, как указано выше. - Twilio не принимает
REFERдля вызова, подключённого через<Conference>или<Queue>, поэтому набирайте агента через<Dial><Sip>, как указано выше.