SIP로 연결하기(전화번호 불필요)

PBX, 통신사 또는 SIP 애플리케이션에서 ThunderPhone 에이전트로 통화를 바로 연결하세요. 통화마다 일회용 SIP URI를 사용하거나 영구 SIP 주소를 사용할 수 있습니다.

자체 시스템에서 이미 전화번호를 처리하는 경우(PBX, 컨택 센터 플랫폼 또는 번호를 순환시키는 통신사 계정) 일반 SIP를 통해 통화를 ThunderPhone 에이전트로 보낼 수 있습니다. ThunderPhone에서 번호를 가져오거나 구매하지 않아도 됩니다. 시스템에서 SIP 주소로 전화를 걸면 에이전트가 응답합니다.

SIP 주소에는 두 가지 유형이 있습니다.

두 유형 모두 조직의 하나의 에이전트로 라우팅되며, 다른 수신 통화와 마찬가지로 통화 기록에 표시됩니다.

통화별 SIP URI#

1. 통화 등록#

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"}
  }'

{
  "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(선택 사항)는 발신 통화와 동일한 방식으로 에이전트 프롬프트의 {{placeholders}}를 채웁니다.
• call_id는 통화가 연결된 후 통화 기록에서 해당 통화가 갖게 될 ID입니다 (GET /v1/calls/{call_id}).

2. URI로 전화 걸기#

5분 이내에 통화를 sip_uri로 전송합니다. URI는 통화 1회에만 사용할 수 있습니다. 통화가 이를 사용하면 해당 통화가 빠르게 종료되더라도 더 이상 사용할 수 없습니다.

예를 들어 Twilio를 사용하는 경우, 전달하려는 통화에 대해 다음 TwiML을 반환합니다.

<Response>
  <Dial>
    <Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
  </Dial>
</Response>

PBX에서는 URI를 SIP 대상으로 다이얼합니다. 사용자 이름이나 비밀번호는 필요하지 않습니다. 토큰이 자격 증명이므로 URI를 사용하기 전까지 비밀번호처럼 취급하십시오.

SIP 엔드포인트(영구 주소)#

1. 엔드포인트 생성#

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"}'

{
  "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"
}

2. 시스템을 엔드포인트로 설정#

다음 설정으로 SIP 트렁크 또는 대상지를 구성하십시오.

이 전송 방식 및 코덱 설정은 통화별 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를 설정하십시오.

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 범위).

발신자와 시스템에 표시되는 내용#

• 발신자 ID: From 헤더의 사용자 부분이 발신자로 저장됩니다. 전화번호(숫자와 선택적으로 +, 공백, 대시, 점 또는 괄호 포함)는 E.164 형식으로 정규화되며, SIP 사용자 이름과 같은 그 외 값은 전송된 그대로 유지됩니다. 최대 32자까지 유지되며, 발신자가 없으면 anonymous로 저장됩니다.
• 거부된 통화: 알 수 없거나 만료된 통화별 URI에는 SIP 404 Not Found가 반환됩니다. 이미 사용된 통화별 URI, 비활성화된 엔드포인트 또는 허용 목록 외부의 소스(허용 목록이 있는 엔드포인트로의 모든 UDP 통화 포함)는 에이전트가 시작되기 전에 연결이 끊깁니다. 시스템에서는 통화 실패로 표시되거나 연결 직후 종료될 수 있습니다. 이러한 거부는 통화 기록 항목을 생성하지 않습니다. 조직의 크레딧이 부족하거나 지출 한도에 도달한 경우 통화가 거부되며, 통화 기록에는 요금 없이 실패한 통화로 표시됩니다. 통화별 시도를 다시 하려면 새 URI를 등록하세요.
• 전환: 에이전트의 콜드 전환은 작동합니다(ThunderPhone이 SIP REFER를 전송하며, 시스템에서 이를 수락해야 합니다). 웜 전환은 SIP 주소 통화에서 사용할 수 없습니다. 두 번째 구간의 발신자 ID로 표시할 ThunderPhone 번호가 없기 때문입니다. Twilio에서는 위의 TwiML이 에이전트를 연결하지만 전환은 처리하지 않습니다. <Dial>에 referUrl="https://YOUR_SERVER/sip-transfer"를 추가하고, 해당 웹훅에서 ReferTransferTarget을 읽어 전환 대상에 전화를 거는 TwiML을 반환하도록 하세요(Twilio의 SIP REFER 가이드 참조).
• 문자 메시지: SIP 주소와 발신한 번호는 문자 메시지를 보낼 수 없습니다. 에이전트가 문자 전송용으로 별도의 SMS 지원 번호를 설정한 경우에만 SIP 주소 통화 중 문자를 보낼 수 있습니다. 그렇지 않으면 SMS 도구를 사용할 수 없습니다.
• 등록: ThunderPhone은 SIP REGISTER를 수락하지 않습니다. 주소로 통화를 보내고 해당 주소에 등록하지 마세요.

가격#

SIP 주소 통화에는 에이전트의 일반 분당 요금이 청구됩니다. 통화에 ThunderPhone 번호가 사용되지 않으므로 전화번호 요금은 없습니다. 자체 통신사는 평소와 같이 통화의 해당 구간에 대해 요금을 청구합니다. 가격을 참조하세요.

테스트하기#

1. 위와 같이 통화별 URI 또는 엔드포인트를 만드세요.
2. 시스템 또는 SIP 소프트폰에서 해당 주소로 전화를 거세요(엔드포인트의 경우 사용자 이름과 비밀번호를 입력하세요).
3. 통화를 종료한 후 대시보드의 통화에서 해당 통화를 열거나 GET /v1/calls/{call_id}로 가져오세요. 발신자, 대상("발신한 번호 전달" 아래의 순서 참조) 및 대화 내용이 표시됩니다.

API 세부 정보: SIP 주소 API 참조.