---
title: "Twilio에서 연결"
description: "CallSid를 사용하여 Twilio 통화를 SIP를 통해 ThunderPhone 에이전트로 전송하고, 전송 주소의 핸드오프와 함께 referUrl을 통해 다시 가져옵니다."
---

TwiML이 헤더에 통화의 `CallSid`를 담아 에이전트의 SIP 주소로 다이얼합니다.
발신자에게 사람이 필요할 때 에이전트는 SIP `REFER`를 전송하고, Twilio는 인계 정보가 포함된
전송 주소를 `referUrl` 핸들러로 전달합니다. 핸들러가 반환하는 TwiML이 발신자의 연결 대상(예: Flex 큐)을 결정합니다.

## 시작 전 준비

- ThunderPhone 에이전트와 조직 [API 키](/ko/guides/api-keys).
- Twilio Programmable Voice 및 TwiML과 `referUrl` 핸들러를 제공할 환경: 자체 서버 또는 TwiML Bin과 Twilio Function. Flex는 선택 사항입니다.

## 1. SIP 엔드포인트 만들기

Twilio의 `<Sip>`는 사용자 이름과 비밀번호를 사용하므로 표준 엔드포인트를 사용합니다.

```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 제한](/ko/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는 자체 call-id 헤더를 문서화하지 않으므로 이 헤더를 추가하십시오. ThunderPhone은 이를 통화의 `external_call_id`로 저장합니다. TwiML Bin에서는 `{{CallSid}}`가 작동합니다. 자체 서버에서는 수신 요청의 `CallSid`를 작성하십시오.
- `&amp;X-Account-Id=12345`처럼 같은 방식으로 컨텍스트를 더 추가합니다. TwiML 내부에서는 일반 `&`가 유효하지 않은 XML이므로 `&`를 `&amp;`로 작성하십시오. 각 값은 프롬프트에 변수로 전달되며, 여기서는 `{{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. 통화를 다시 연결하기

에이전트는 핸드오프 ID와 인텐트가 포함된 전송 주소를 가진 `REFER`로 전송합니다. 이 전송 번호를 추가합니다([전송 번호 추가](/ko/guides/contact-centers/overview) 및 [전송 주소 내부의 헤더](/ko/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는 전체 주소를 `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에서 실행됩니다.

```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 키는 Function의 환경 변수에 보관합니다. 다른 필드는
[핸드오프된 통화 조회](/api-reference/calls#look-up-a-handed-off-call)를 참조합니다.

## 테스트하기

위 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>`으로 에이전트에 연결합니다.
