Open in
Twilio에서 연결
CallSid를 사용하여 Twilio 통화를 SIP를 통해 ThunderPhone 에이전트로 전송하고, 전송 주소의 핸드오프와 함께 referUrl을 통해 다시 가져옵니다.
TwiML이 헤더에 통화의 CallSid를 담아 에이전트의 SIP 주소로 다이얼합니다.
발신자에게 사람이 필요할 때 에이전트는 SIP REFER를 전송하고, Twilio는 인계 정보가 포함된
전송 주소를 referUrl 핸들러로 전달합니다. 핸들러가 반환하는 TwiML이 발신자의 연결 대상(예: Flex 큐)을 결정합니다.
시작 전 준비
- ThunderPhone 에이전트와 조직 API 키.
- Twilio Programmable Voice 및 TwiML과
referUrl핸들러를 제공할 환경: 자체 서버 또는 TwiML Bin과 Twilio Function. Flex는 선택 사항입니다.
1. SIP 엔드포인트 만들기
Twilio의 <Sip>는 사용자 이름과 비밀번호를 사용하므로 표준 엔드포인트를 사용합니다.
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는 자체 call-id 헤더를 문서화하지 않으므로 이 헤더를 추가하십시오. ThunderPhone은 이를 통화의external_call_id로 저장합니다. TwiML Bin에서는{{CallSid}}가 작동합니다. 자체 서버에서는 수신 요청의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. 통화를 다시 연결하기
에이전트는 핸드오프 ID와 인텐트가 포함된 전송 주소를 가진 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는 전체 주소를 ReferTransferTarget으로 referUrl에 전송합니다. 예:
<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>.
핸들러는 여기에서 헤더를 읽고 발신자가 다음으로 연결될 대상에 대한 TwiML을 반환합니다.
주소의 사용자 부분(support)은 선택할 수 있으므로 대상별로 전송 번호를 하나씩 추가하고 이를 기준으로 라우팅할 수 있습니다.
이 Twilio Function은 핸드오프를 작업 속성으로 사용하여 발신자를 Flex에 대기열로 추가하고 핸드오프 ID로 요약을 조회합니다. Studio의 HTTP Request 위젯은 Authorization
헤더를 보낼 수 없으므로 조회는 Function에서 실행됩니다.
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 키는 Function의 환경 변수에 보관합니다. 다른 필드는 핸드오프된 통화 조회를 참조합니다.
테스트하기
위 TwiML을 반환하는 Twilio 번호로 전화하고 에이전트에게 담당자와 연결해 달라고 요청한 다음,
referUrl 핸들러가 두 헤더를 모두 포함한 ReferTransferTarget을 수신하고 발신자가 대기열에 도달하는지 확인합니다. 그런 다음
GET /v1/calls/{call_id}로 통화를 엽니다. external_call_id는 CallSid여야 합니다.
제한 사항
- Twilio는
Refer-To를 256자로 제한합니다. ThunderPhone은 주소를 254자로 유지하고 맞지 않는 헤더는 제외하므로 헤더 이름과 값을 짧게 유지합니다. - Twilio는
BYE에서 헤더를 읽는 방법을 문서화하지 않았으므로 반환 시 핸드오프를 Twilio로 다시 전달할 수 없습니다. 위와 같이REFER를 사용합니다. - Twilio는
<Conference>또는<Queue>를 통해 연결된 통화에서REFER를 허용하지 않으므로 위와 같이<Dial><Sip>으로 에이전트에 연결합니다.