피드백을 보내 주셔서 감사합니다.

상세 통화 기록 웹훅은 요청이 아닌 이벤트를 기반으로 하는 안전하고 확장 가능하며 강력한 솔루션을 제공해요. 이 웹훅은 청구에서 맞춤형 보고에 이르기까지 사용 사례를 지원하여 고객 Webex Calling 활동을 더 잘 볼 수 있게 해줘요.

이 웹훅을 사용하면 각 고객을 개별적으로 쿼리하지 않고도 파트너 허브를 통해 관리되는 모든 고객에 대한 기록을 편리하게 수집할 수 있어요. 이 웹훅을 사용하면 내부 비즈니스 요구 사항과 부가가치 서비스 모두에 대한 사용자 지정 보고, 청구 및 분석 애플리케이션을 개발할 수 있어요.

웹훅과 그에 수반되는 API에 대한 소개는 이 비디오캐스트: Webex Calling 파트너 세부 통화 기록 API를 봐요.

파트너 웹훅이 제공하는 것

웹훅은 5분마다 상세한 통화 기록 기록을 보여줘요. 각 웹후크 페이로드에는 다음이 포함돼요.

• 현재 시간보다 10분에서 5분 전에 종료된 통화 기록.
• Webex Calling클라우드에서 처리된 모든 지연 기록.
• 안정적인 전송을 보장하기 위해 후속 웹후크 페이로드의 늦은 통화 기록을 자동으로 채워 줘요.

각 페이로드에 통화 기록이 어떻게 포함되는지 표시하려면 다음 예를 고려해 보세요.

• 14:05 에 받은 페이로드에는 13:55 에서 14:00 사이에 종료된 통화가 포함돼요.
• 14:00 에서 14:05 사이에 끝나는 통화는 14:10 페이로드에 포함돼요.
• 더 일찍 완료했지만 (예: 14:04 에 종료된 통화) Webex Calling 클라우드에서 늦게 처리한 기록 (예: 14:11) 은 다음 예약 페이로드에 포함돼요 (예 : 14:15).

파트너 허브의 웹후크

웹훅을 제공하면 분석 플랫폼에서 통화 기록을 생성할 때마다 콜백 URL로 보낼 수 있어요.

Webex Calling기록은 기존의 상세 통화 기록 API와 같은 형식으로 전달돼요. 웹훅을 설정하고 두 가지 피드 중 하나를 선택할 수 있어요.

• 분석—파트너와 관계를 맺고 있는 모든 고객 조직의 모든 통화 기록을 포함해요. Webex Calling 여기에는 다음과 같은 조직도 포함돼요.
  • 파트너는 파트너 전체 관리자 역할로 고객 조직을 관리해요.
  • 고객 조직은 파트너 조직 내에서 Webex Calling 구독이 활성화되어 있어요.
• 청구—파트너가 판매하고 제공해준 Webex Calling 라이선스를 가진 사용자들이 걸었던 통화에 대한 통화 기록이 포함돼요. 작업공간 통화 기록이 이 피드에 포함돼요.

액세스 및 데이터 프라이버시

소유 파트너만 청구 시 통화 정보 기록 (CDR) 에 액세스할 수 있어요.

• 통화 녹음과 관련된 라이선스를 관리하는 파트너 (또는 하위 파트너) 가 소유 파트너가 돼요.
• 소유권은 사용자 ID > 라이선스 ID > 구독 ID > 파트너 ID로 결정돼요.
• 한 명의 파트너가 각 CDR에 액세스할 수 있어요.
• 일부 통화 기록은 청구 파트너와 매핑되지 않고, 조직과 관련된 모든 파트너가 모든 기록에 동등하게 접근할 수 있는 것은 아니에요. 이러한 기록에는 개인 식별 정보 (PII) 가 포함될 수 있기 때문입니다.

웹후크 외에도 데이터 조정을 지원하는 API 엔드포인트를 Webex Calling 제공해요. 이 엔드포인트를 사용하면 웹후크 리스너가 받지 못했을 수도 있는 누락된 레코드를 데이터스토어를 따라잡거나 조정할 수 있어요. API 엔드포인트 두 개가 조정 API하고 레코드 API예요.

이 API의 레코드는 30일 동안 사용할 수 있어요. 예상 레코드를 모두 받을 수 있도록 주기적으로, 예를 들어 12시간이나 24시간마다 레코드 저장소를 조정하는 것이 좋아요.

이 API에 액세스하려면 파트너 액세스 토큰을 사용해야 해요. 인증 사용자는 조직의 전체 관리자 수준 액세스 권한이 있는 파트너 전체 관리자여야 하고 Webex CallingCDR API 액세스를 활성화해야 해요. OAuth 토큰은 범위를 포함해야 해요. spark-admin:calling_cdr_read 읽기 전용 관리자 역할은 파트너 조정 및 기록 API에 충분하지 않아요.

고객 조직의 Webex Calling 데이터 지역에 analytics-calling엔드포인트를 사용하세요. 조정 API와 기록 API 모두에 해당 기본 URL을 사용하세요.

• 미국과 캐나다: https://analytics-calling.webexapis.com
• 유럽: https://analytics-calling-eu.webexapis.com
• 인도: https://analytics-calling-in.webexapis.com
• 오스트레일리아: https://analytics-calling-au.webexapis.com

조정 API 엔드포인트

조정 API 엔드포인트는 지정된 기간 내에 파트너가 관리하는 각 고객에 대해 생성된 총 통화 기록 수를 반환해요. 이 합계를 사용하여 로컬 스토리지를 확인하고 특정 고객의 누락되거나 일치하지 않는 통화 기록을 식별할 수 있어요.

고객 조직을 200개 이상 관리하는 경우 API가 결과를 페이지별로 분류해서 가독성을 높여줘요.

조정 API 엔드포인트 URL은 다음 형식을 사용해요.

API 파라미터

API를 사용하여 지난 30일간의 통화 기록을 검색할 수 있어요. 선택한 시간 창은 현재 UTC 시간보다 최소 5분 전에 시작해야 하고 단일 API 호출에서 시작 시간과 종료 시간 사이 12시간을 초과할 수 없어요.

API 매개변수는 다음과 같아요.

• 시작 시간 (필수, 문자열) - 수집하려는 첫 번째 레코드의 시작 날짜 및 시간 (UTC) 이에요. 꼭 확인해 주세요:
  • 시간 형식을 다음과 같이 지정해요 YYYY-MM-DDTHH:MM:SS.mmmZ. 예를 들자면, 2025-08-15T06:00:00.000Z.
  • 시작 날짜와 시간은 현재 UTC 시간으로부터 30일을 넘으면 안 돼요.
  • 그 startTime사이의 기간은 12시간을 endTime초과할 수 없어요.
• 종료 시간 (필수, 문자열) - 수집하려는 레코드의 종료 날짜 및 시간 (UTC) 이에요. 기록은 보고 시간, 통화 완료 시간을 기준으로 해요. 꼭 확인해 주세요:
  • 시간 형식을 다음과 같이 지정해요 YYYY-MM-DDTHH:MM:SS.mmmZ. 예를 들자면, 2025-08-15T18:00:00.000Z.
  • 종료 날짜와 시간은 현재 UTC 시간보다 5분 전이어야 하고 30일 이전이어야 해요.
  • 종료 날짜와 시간은 보다 커야 해요 startTime.
  • 와 사이의 기간은 startTime12시간을 endTime초과할 수 없어요.

조정 API 엔드포인트 JSON 응답의 예시:

          {
          "cdr_counts": [
          {
          "orgId": "zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
          "count": 3009
          },
          {
          "orgId": "yyyyyyyy-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
          "count": 129
          },
          {
          "orgId": "xxxxxxxx-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
          "count": 27895
          }
          ]
          }          
        

API 응답 헤더는 반환된 전체 조직 수와 추가 페이지 사용 가능 여부를 나타냅니다. 다음 헤더 매개 변수를 확인하여 모든 페이지를 쿼리했는지 확인하세요.

• 페이지 수: 총 페이지 수 (예: 2)
• 전체 조직: 응답에 포함된 전체 조직 수 (예: 283개)
• 현재 페이지: 현재 페이지 번호 (예: 1)

예를 들어 헤더에 페이지 수=2, 총 조직=283, 현재 페이지=1이면 총 283개 조직이 포함된 두 페이지짜리 응답의 첫 페이지를 보고 있는 거예요. 다음 페이지에 액세스하려면 아래 그림과 같이 GET 요청에 page=2 매개 변수를 추가하세요.

https://analytics-calling.webexapis.com/v1/partners/cdrcountbyorg?endTime=YYYY-MM-DDTHH:MM:SS.000Z&startTime=YYYY-MM-DDTHH:MM:SS.000Z&page=2

레코드 API 엔드포인트

레코드 API 엔드포인트는 조정 API를 사용하여 불일치나 누락된 데이터를 식별한 특정 조직의 누락된 통화 기록을 쿼리하는 데 사용돼요.

권장 흐름: /v1/partners/cdrcountbyorg먼저 전화하세요. 그럼 cdr_counts[].orgId전화할 때 orgId반송된 정확한 번호를 사용하세요 /v1/partners/cdrsbyorg.

레코드 API는 통화 기록을 상세 통화 기록 API에 설명된 형식과 동일한 JSON 형식으로 반환해요. 반환된 페이로드에는 반환된 통화 내역 상세 페이로드와 동일한 필드가 들어 있어요. 필드 및 해당 값에 대한 Webex Calling자세한 내용은 상세 통화 기록 보고서를 참조하세요.

API는 현재 시간보다 5분 전에 종료된 통화 기록을 제공해요. 모든 통화 기록을 사용할 수 있게 하려면 원하는 시간보다 한 시간 후에 API를 쿼리하는 것이 좋아요.

레코드 API 엔드포인트 URL은 다음 형식을 사용해요.

https://analytics-calling.webexapis.com/v1/partners/cdrsbyorg?orgId=zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy&endTime=YYYY-MM-DDTHH:MM:SS.000Z&startTime=YYYY-MM-DDTHH:MM:SS.000Z

API 파라미터

• orgId(필수, 문자열) —레코드를 검색하려는 고객 조직 ID예요. 파라미터 이름은 대소문자를 구분해요. 조정 API 응답 필드에서 조직 ID를 얻을 수 있어요. cdr_counts[].orgId
• 시작 시간 (필수, 문자열) - 수집하려는 첫 번째 레코드의 시작 날짜 및 시간 (UTC) 이에요. 꼭 확인해 주세요:
  • 시간 형식을 다음과 같이 지정해요 YYYY-MM-DDTHH:MM:SS.mmmZ. 예를 들자면, 2025-08-15T06:00:00.000Z.
  • 시작 날짜와 시간은 현재 UTC 시간으로부터 30일을 넘으면 안 돼요.
  • 단일 API 요청에서 startTime와 사이의 간격은 12시간을 endTime초과해서는 안 돼요.
• 종료 시간 (필수, 문자열) - 수집하려는 마지막 레코드의 종료 날짜 및 시간 (UTC) 이에요. 기록은 보고 시간, 통화 완료 시간을 기준으로 해요. 꼭 확인해 주세요:
  • 시간 형식을 다음과 같이 지정해요 YYYY-MM-DDTHH:MM:SS.mmmZ. 예를 들자면, 2025-08-15T18:00:00.000Z.
  • 종료 날짜와 시간은 현재 UTC 시간보다 최소 5분 전이어야 하고 30일 미만이어야 해요.
  • 종료 날짜와 시간은 보다 커야 해요 startTime.
  • 단일 API 요청에서 startTime와 사이의 간격은 12시간을 endTime초과해서는 안 돼요.
• max (선택 사항, 개수) —응답 페이지당 최대 레코드 수를 제한해요. 꼭 확인해 주세요:
  • 범위는 500에서 5000까지입니다. 기본값은 5000이에요. 예를 들자면, max=1000.
  • API가 반환할 레코드가 지정된 최대값보다 많으면 응답에 페이지 매김이 돼요.
  • 500 미만으로 값을 지정하면 500까지 자동으로 조정돼요. 5000보다 큰 값을 지정하면 5000으로 조정돼요.

페이지 매김

API 응답이 페이지 매김되었는지 확인하려면 링크 헤더의 응답 헤더를 확인하세요. next링크 헤더에 링크가 있으면 추출하고 startTimeForNextFetch값을 사용하여 다음 레코드 세트를 요청하세요. 다음 링크가 없으면 선택한 시간 범위의 모든 보고서가 수집돼요.

후속 페이지에 대한 API 요청은 즉시 할 수 있지만 토큰 범위당 분당 페이지 매김 요청 최대 10개로 속도를 제한해야 해요.

페이지 매김 응답이나 반복되는 조정 창을 포함하여 기록을 검색할 때 등점 처리와 중복 제거를 사용하세요. 기본 reportId키로 사용하고 가장 최근에 처리된 레코드를 결정하는 reportTime데 사용해요.

예를 들어, 초기 API 요청이 다음과 같은 경우

https://analytics-calling.webexapis.com/v1/partners/cdrsbyorg?orgId=zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy&endTime=2025-08-15T18:00:00.000Z&startTime=2025-08-15T06:00:00.000Z&max=5000

그러면 응답의 링크 헤더는 다음과 같아요.

<https://analytics-calling.webexapis.com/v1/partners/cdrsbyorg?orgId=zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy&endTime=2025-08-15T18:00:00.000Z&startTime=2025-08-15T06:00:00.000Z&startTimeForNextFetch=2025-08-15T09:30:00.000Z&totalCount=20000&max=5000>; rel="next"

페이지네이션은 rel="next"링크 헤더만 사용해요. 응답에 rel="next"링크가 포함되면 그 URL을 사용하여 레코드의 다음 페이지를 검색하세요. 응답에 rel="next"링크가 포함되어 있지 않으면 선택한 시간 범위 동안 사용 가능한 모든 레코드를 검색한 것입니다.

파트너 보고서 API를 사용하여 파트너 허브에서 보고서를 생성하고 다운로드할 수 있어요. 자세한 내용은 파트너 보고서/템플릿을 참조하세요.

파트너는 파트너 허브에서 직접 여러 보고서를 액세스하고 다운로드할 수도 있어요. 자세한 내용은 파트너 허브 보고서를 참조하세요.