--- title: "SIP로 연결하기(전화번호 불필요)" description: "PBX, 통신사 또는 SIP 애플리케이션에서 ThunderPhone 에이전트로 통화를 바로 연결하세요. 통화마다 일회용 SIP URI를 사용하거나 영구 SIP 주소를 사용할 수 있습니다." --- 자체 시스템에서 이미 전화번호를 처리하는 경우(PBX, 컨택 센터 플랫폼 또는 번호를 순환시키는 통신사 계정) 일반 SIP를 통해 통화를 ThunderPhone 에이전트로 보낼 수 있습니다. ThunderPhone에서 번호를 가져오거나 구매하지 않아도 됩니다. 시스템에서 SIP 주소로 전화를 걸면 에이전트가 응답합니다. SIP 주소에는 두 가지 유형이 있습니다. | | **통화별 SIP URI** | **SIP 엔드포인트** | |---|---|---| | 형태 | `sip:c-@sip.thunderphone.com` | `sip:agent--@sip.thunderphone.com` | | 생성 방법 | 통화마다 한 번 `POST /v1/calls/register-sip` | 한 번 `POST /v1/sip-endpoints` | | 인증 | 주소에 포함된 일회용 토큰 | SIP 다이제스트 사용자 이름 + 비밀번호(선택적으로 소스 IP 허용 목록) | | 적합한 경우 | 통화를 전달하기 전에 이미 API를 호출하는 앱, 통화별 변수 | ThunderPhone으로 트렁크를 연결하기만 하면 되는 PBX 및 통신사 | | 유효 기간 | 5분, 통화 1회 | 삭제할 때까지 | 두 유형 모두 조직의 하나의 에이전트로 라우팅되며, 다른 수신 통화와 마찬가지로 통화 기록에 표시됩니다. ## 통화별 SIP URI ### 1. 통화 등록 ```bash curl -X POST https://api.thunderphone.com/v1/calls/register-sip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": 12, "to_number": "+14155550142", "variables": {"customer_name": "Ada"} }' ``` ```json { "call_id": 862197007562, "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com", "expires_at": "2026-09-25T21:49:52Z", "agent_id": 12, "to_number": "+14155550142" } ``` - `to_number`(선택 사항)는 발신자가 귀하의 시스템에서 건 번호입니다. 이 번호는 통화 기록에서 통화의 목적지로 저장되며, 에이전트는 이를 자신의 번호로 인식합니다. - `variables`(선택 사항)는 [발신 통화](/ko/guides/call-variables)와 동일한 방식으로 에이전트 프롬프트의 `{{placeholders}}`를 채웁니다. - `call_id`는 통화가 연결된 후 통화 기록에서 해당 통화가 갖게 될 ID입니다 (`GET /v1/calls/{call_id}`). ### 2. URI로 전화 걸기 5분 이내에 통화를 `sip_uri`로 전송합니다. URI는 통화 1회에만 사용할 수 있습니다. 통화가 이를 사용하면 해당 통화가 빠르게 종료되더라도 더 이상 사용할 수 없습니다. 예를 들어 Twilio를 사용하는 경우, 전달하려는 통화에 대해 다음 TwiML을 반환합니다. ```xml sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp ``` PBX에서는 URI를 SIP 대상으로 다이얼합니다. 사용자 이름이나 비밀번호는 필요하지 않습니다. 토큰이 자격 증명이므로 URI를 사용하기 전까지 비밀번호처럼 취급하십시오. ## SIP 엔드포인트(영구 주소) ### 1. 엔드포인트 생성 ```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": "Main PBX"}' ``` ```json { "id": 7, "name": "Main PBX", "agent_id": 12, "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com", "username": "tp409667538f83", "password": "8mJ0…", "allowed_source_cidrs": [], "status": "active", "created_at": "2026-09-25T21:46:18Z" } ``` `password`는 엔드포인트 생성 시 한 번만 반환됩니다. 즉시 PBX 또는 통신사 구성에 저장하십시오. 분실한 경우 `POST /v1/sip-endpoints/{id}/rotate-password`로 변경하십시오. ### 2. 시스템을 엔드포인트로 설정 다음 설정으로 SIP 트렁크 또는 대상지를 구성하십시오. | 설정 | 값 | |---|---| | SIP URI | 엔드포인트의 `sip_uri` | | 사용자 이름 / 비밀번호 | `username` / `password`(다이제스트 인증, ThunderPhone이 각 통화에 대해 인증 요청) | | 전송 방식 | 포트 5060의 TCP 또는 포트 5061의 TLS(권장), 또는 포트 5060의 UDP | | 코덱 | G.711(PCMU/PCMA) 또는 G.722 | TCP 또는 TLS를 사용하는 것이 좋습니다. UDP는 공인 주소와 대부분의 NAT에서 작동하지만, "대칭형" NAT(대상마다 새 포트를 사용하는 NAT) 뒤에서는 에이전트의 통화 종료 및 전환이 시스템에 도달하지 않을 수 있습니다. 소스 IP 허용 목록(아래)도 TCP 또는 TLS가 필요합니다. TLS를 사용하면 SIP 시그널링은 `sip.thunderphone.com`을 지난 후에도 통화를 처리하는 서버까지 계속 암호화됩니다. 이 전송 방식 및 코덱 설정은 통화별 URI에도 적용됩니다. 두 종류의 주소 모두에서 다음 네트워크 세부 사항이 중요합니다. - **Record-Route를 따르십시오.** 첫 번째 INVITE 이후 나머지 통화 시그널링(ACK, 통화 종료, 전환)은 응답한 특정 ThunderPhone 서버로 전달됩니다. 이 서버는 `Record-Route` 헤더에 명시되어 있습니다 (`sip-1.thunderphone.com` 또는 `sip-2.thunderphone.com`, 또는 해당 IP 주소). 아웃바운드 SIP를 제한하는 경우 `sip.thunderphone.com`뿐 아니라 해당 호스트도 허용하십시오. `172.170.39.202`(`sip`), `13.86.104.121` (`sip-1`), `20.80.98.90`(`sip-2`)입니다. - **오디오는 다른 곳으로 전송됩니다.** `sip.thunderphone.com`은 시그널링만 처리합니다. SDP 응답에 있는 주소 및 포트로 미디어(RTP)를 허용하십시오. 주소로 들어오는 모든 통화는 발신자가 귀하 측에서 건 번호와 관계없이 엔드포인트의 에이전트에 연결됩니다. 번호를 가져올 필요가 없으므로 귀하 측에서 번호를 변경해도 ThunderPhone에서는 변경할 사항이 없습니다. ### 발신자가 건 번호 전달(선택 사항) 발신자가 귀하의 어떤 번호로 전화를 걸었는지 기록하려면 INVITE의 `X-Original-To` 헤더(예: `X-Original-To: +14155550142`) 또는 표준 `Diversion` 헤더로 해당 번호를 전송하십시오. ThunderPhone은 이를 통화의 수신 번호로 저장합니다. 수신 번호는 다음 순서로 선택됩니다. 통화별 URI 등록 시 지정한 `to_number`, 그다음 `X-Original-To`의 번호, 그다음 `Diversion`의 번호입니다. 어느 항목에서도 번호를 얻지 못하면 엔드포인트에서는 `sip:agent-12-jhxmginwjx`(엔드포인트 주소)로, 통화별 URI에서는 `sip:call`로 표시됩니다. Twilio에서는 SIP URI에 헤더를 추가할 수 있습니다. `sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142`. ### 소스 IP 제한(선택 사항) 사용자 이름 및 비밀번호에 더해, 자체 시그널링 주소에서 오는 통화만 허용하도록 `allowed_source_cidrs`를 설정하십시오. ```bash curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}' ``` 다른 주소에서 온 통화는 에이전트에 도달하기 전에 거부됩니다. 미디어 주소가 아니라 시스템에서 SIP 시그널링을 보내는 주소를 사용하십시오(예: Twilio와 같은 통신사의 경우 공개된 시그널링 IP 범위). 허용 목록은 TCP 또는 TLS를 통한 통화에 대해서만 확인됩니다. UDP 소스 주소는 위조할 수 있으므로 허용 목록이 있는 엔드포인트는 UDP로 들어오는 모든 통화를 거부합니다. `;transport=tcp`(포트 5060)를 사용하거나 TLS(포트 5061)로 통화를 전송하십시오. ## 발신자와 시스템에 표시되는 내용 - **발신자 ID:** `From` 헤더의 사용자 부분이 발신자로 저장됩니다. 전화번호(숫자와 선택적으로 `+`, 공백, 대시, 점 또는 괄호 포함)는 E.164 형식으로 정규화되며, SIP 사용자 이름과 같은 그 외 값은 전송된 그대로 유지됩니다. 최대 32자까지 유지되며, 발신자가 없으면 `anonymous`로 저장됩니다. - **거부된 통화:** 알 수 없거나 만료된 통화별 URI에는 SIP `404 Not Found`가 반환됩니다. 이미 사용된 통화별 URI, 비활성화된 엔드포인트 또는 허용 목록 외부의 소스(허용 목록이 있는 엔드포인트로의 모든 UDP 통화 포함)는 에이전트가 시작되기 전에 연결이 끊깁니다. 시스템에서는 통화 실패로 표시되거나 연결 직후 종료될 수 있습니다. 이러한 거부는 통화 기록 항목을 생성하지 않습니다. 조직의 크레딧이 부족하거나 지출 한도에 도달한 경우 통화가 거부되며, 통화 기록에는 요금 없이 실패한 통화로 표시됩니다. 통화별 시도를 다시 하려면 새 URI를 등록하세요. - **전환:** 에이전트의 콜드 전환은 작동합니다(ThunderPhone이 SIP `REFER`를 전송하며, 시스템에서 이를 수락해야 합니다). 웜 전환은 SIP 주소 통화에서 사용할 수 없습니다. 두 번째 구간의 발신자 ID로 표시할 ThunderPhone 번호가 없기 때문입니다. Twilio에서는 위의 TwiML이 에이전트를 연결하지만 전환은 처리하지 않습니다. ``에 `referUrl="https://YOUR_SERVER/sip-transfer"`를 추가하고, 해당 웹훅에서 `ReferTransferTarget`을 읽어 전환 대상에 전화를 거는 TwiML을 반환하도록 하세요(Twilio의 [SIP REFER 가이드](https://www.twilio.com/docs/voice/api/refer-to-twilio) 참조). - **문자 메시지:** SIP 주소와 발신한 번호는 문자 메시지를 보낼 수 없습니다. 에이전트가 문자 전송용으로 별도의 SMS 지원 번호를 설정한 경우에만 SIP 주소 통화 중 문자를 보낼 수 있습니다. 그렇지 않으면 SMS 도구를 사용할 수 없습니다. - **등록:** ThunderPhone은 SIP `REGISTER`를 수락하지 않습니다. 주소로 통화를 보내고 해당 주소에 등록하지 마세요. ## 가격 SIP 주소 통화에는 에이전트의 일반 분당 요금이 청구됩니다. 통화에 ThunderPhone 번호가 사용되지 않으므로 전화번호 요금은 없습니다. 자체 통신사는 평소와 같이 통화의 해당 구간에 대해 요금을 청구합니다. [가격](/ko/guides/pricing)을 참조하세요. ## 테스트하기 1. 위와 같이 통화별 URI 또는 엔드포인트를 만드세요. 2. 시스템 또는 SIP 소프트폰에서 해당 주소로 전화를 거세요(엔드포인트의 경우 사용자 이름과 비밀번호를 입력하세요). 3. 통화를 종료한 후 대시보드의 **통화**에서 해당 통화를 열거나 `GET /v1/calls/{call_id}`로 가져오세요. 발신자, 대상("발신한 번호 전달" 아래의 순서 참조) 및 대화 내용이 표시됩니다. API 세부 정보: [SIP 주소 API 참조](/api-reference/sip-addresses).