대화 구성원 API

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 11분

    • 대화 구성원 API는 지정된 에이전트 채팅 대화에서 특정 에이전트의 구성원 상태를 제거됨 또는 업데이트됨으로 변경하는 메서드를 제공합니다.

    이 API는 대화형 인터페이스 환경에서 대화 에이전트 채팅 에서 에이전트 구성원의 상태를 프로그래밍 방식으로 관리하는 기능을 제공합니다. 자세한 내용은 에이전트 채팅 을 참조하십시오.

    이 API는 기본적으로 사용할 수 있습니다. 호출하는 사용자에게 awa_integration_user 역할이 있어야 합니다.

    대화 구성원 - PUT /now/conversation/member/{user_id}/drop

    대화에서 에이전트를 삭제합니다.

    URL 형식

    기본 URL: /api/now/conversation/member/{user_id}/drop

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    user_id 대화에서 삭제할 에이전트의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 사용자 [sys_user]
    표 2. 쿼리 매개변수
    이름 설명
    없음
    표 3. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    interaction_id 필수 에이전트를 삭제할 대화 기록의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 상호작용 [interaction]

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 4. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    콘텐츠-형식 요청 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 5. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 6. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400대화 구성원 작업을 처리하는 동안 오류가 발생했습니다. 예:
    • 제공된 상호작용에 대한 대화를 찾을 수 없습니다.
    • 사용자가 제공된 상호작용 대화의 구성원이 아닙니다.

      요청에 다른 user_id 또는 interaction_id 제공합니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 금지되었습니다. 사용자에게 지정된 기록에 대한 액세스 권한이 없습니다.

    응답 본문 매개변수(JSON 또는 XML)

    이름 설명
    conversation_member 삭제 요청이 처리된 후 대화 구성원으로서의 에이전트 상태에 대한 정보를 포함하는 객체입니다.

    데이터 유형: 객체

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    conversation_member.active 현재 사용자가 대화에 참여하고 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 에이전트가 대화에서 활성 상태입니다.
    • false: 에이전트가 대화에서 삭제되고 더 이상 채팅의 활성 참가자가 아닙니다.

    데이터 유형: 부울
    conversation_member.memberType 구성원 에이전트의 유형입니다.
    가능한 값:
    • public_fulfiller: 에이전트가 지정된 대화에서 다른 에이전트 및 요청자와 공개적으로 채팅할 수 있습니다.
    • 관찰자: 관리자 역할이 있는 사용자만 사용할 수 있습니다. 대화에 참가하지 않고 대화 내용을 볼 수 있는 권한을 부여합니다.
    • private_fulfiller: 에이전트가 에이전트 간의 비공개 채팅에 참가하여 활성 대화에 대해 논의할 수 있습니다.

    데이터 유형: 문자열

    테이블: 대화 구성원 [sys_cs_conversation_member]
    conversation_member.대화_ID 필수 에이전트가 삭제된 대화 기록의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 상호작용 [interaction]
    성공 에이전트 삭제 프로세스가 성공했는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 에이전트가 성공적으로 삭제되었습니다.
    • false: 에이전트를 삭제하지 못했으며 여전히 대화에서 활성 상태로 간주됩니다.

    데이터 유형: 부울
    메시지 할당 또는 예외가 성공했음을 확인하는 응답 메시지입니다.

    성공 메시지: 에이전트 삭제 요청이 성공적으로 처리되었습니다.

    가능한 예외:
    • 잘못된 요청입니다. 불충분 입력: 에이전트 sys_id 또는 상호작용 sys_id 요청에 제공되지 않았습니다.
    • 제공된 상호작용이 외부 공급업체 상호작용이 아닙니다. 요청은 외부 공급업체 상호작용에 대해서만 작동하며 지정된 interaction_id 외부 공급업체 상호작용이 아닙니다.
    • 해당 상호작용에 대한 대화를 찾을 수 없음: 지정된 상호작용 sys_id 있는 해당 대화 기록을 찾을 수 없습니다.
    • 잘못된 요청입니다. 사용자가 제공된 상호작용의 구성원이 아닙니다. 에이전트 sys_id 주어진 상호작용 대화의 구성원이 아닙니다.

    데이터 유형: 문자열

    cURL 요청

    다음 예는 지정된 상호작용 ID에서 지정된 에이전트의 사용자 ID를 삭제하는 방법을 보여줍니다.

    curl "https://instance.servicenow.com/api/now/conversation/member/0b10223c57a313005baaaa65ef94f970/drop" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{\" interaction_id":\"27f675e3739713004a905ee515f6a7c3\"}" \ 
--user 'username':'password'

    응답은 상호작용에서 지정된 에이전트에 대한 성공적인 삭제 작업을 보여줍니다. 활성 필드는 false로 설정되고 메시지는 삭제 작업이 성공했음을 나타냅니다.

    {
  "result": {
    "conversation_member": {
      "active": false,
      "memberType": "public_fulfiller",
      "conversation_id": "27f675e3739713004a905ee515f6a7c3"
    },
    "success": true,
    "message": "Request to drop agent processed successfully."
  }
}

    대화 구성원 - PUT /now/conversation/member/{user_id}/update

    지정된 대화에서 에이전트의 구성원 유형을 관찰자 또는 비공개 이행자 유형에서 공개 이행자로 업데이트합니다.

    이 엔드포인트를 사용하여 에이전트의 현재 관찰자 또는 비공개 이행자 유형을 공개 이행자 유형으로 업데이트할 수만 있습니다. 이 엔드포인트는 에이전트를 관찰자 또는 개인 형식으로 다시 전환하는 것을 지원하지 않습니다. 지정된 에이전트가 이미 공개 이행자 역할을 보유하고 있는 경우 응답은 500 상태 코드를 반환합니다.

    다음 시나리오는 대화 멤버 PUT 업데이트 끝점을 사용하여 에이전트의 구성원 형식을 업데이트하는 방법의 예입니다.
    1. 감독자는 에이전트가 도움을 요청하는 진행 중인 대화를 열고 관찰합니다.
    2. 감독자는 대화를 통해 도움을 제공하기로 결정하고 UI에서 "대화 참여" 버튼을 클릭합니다. 대화 참가 요청이 외부 공급업체 서버로 전송됩니다.
    3. 외부 공급업체 서버는 대화 참여 요청을 처리하고 대화 구성원 PUT 업데이트 엔드포인트를 호출하고 감독자의 구성원 유형을 관찰자에서 공개 이행자로 업데이트합니다.
    4. 에이전트의 클라이언트 UI는 업데이트된 대화 상태를 반영합니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/conversation/member/{user_id}/update

    기본 URL: /api/now/conversation/member/{user_id}/update

    지원되는 요청 매개변수

    표 7. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    user_id 대화에서 새 구성원 유형으로 업데이트할 에이전트의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 사용자 [sys_user]
    표 8. 쿼리 매개변수
    이름 설명
    없음
    표 9. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    interaction_id 필수 에이전트 구성원 유형을 업데이트할 대화 기록의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 상호작용 [interaction]
    member_type 필수 지정된 대화에서 에이전트를 업데이트할 구성원의 유형입니다.

    유효한 값: public_fulfiller

    데이터 유형: 문자열

    테이블: 대화 구성원 [sys_cs_conversation_member], 필드: 구성원 유형

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 10. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 11. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 12. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 대화 구성원 작업을 처리하는 동안 오류가 발생했습니다.
    예:
    • 제공된 상호작용에 대한 대화를 찾을 수 없습니다.
    • 사용자가 제공된 상호작용 대화의 구성원이 아닙니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 금지되었습니다. 사용자에게 지정된 기록에 대한 액세스 권한이 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON 또는 XML)

    이름 설명
    conversation_member 업데이트 요청이 처리되면 에이전트 구성원의 상태에 대한 정보를 포함하는 객체입니다.

    데이터 유형: 객체

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    conversation_member.active 현재 사용자가 대화에 참여하고 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 에이전트가 대화에서 활성 상태입니다.
    • false: 에이전트가 대화에서 삭제되고 더 이상 채팅의 활성 참가자가 아닙니다.

    데이터 유형: 부울
    conversation_member.memberType 구성원 에이전트의 유형입니다.
    가능한 값:
    • public_fulfiller: 에이전트가 지정된 대화에서 다른 에이전트 및 요청자와 공개적으로 채팅할 수 있습니다.
    • 관찰자: 관리자 역할이 있는 사용자만 사용할 수 있습니다. 대화에 참가하지 않고 대화 내용을 볼 수 있는 권한을 부여합니다.
    • private_fulfiller: 에이전트가 에이전트 간의 비공개 채팅에 참가하여 활성 대화에 대해 논의할 수 있습니다.

    데이터 유형: 문자열

    테이블: 대화 구성원 [sys_cs_conversation_member]
    conversation_member.대화_ID 에이전트가 업데이트된 대화 기록의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 상호작용 [interaction]
    성공 업데이트 프로세스가 성공했는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 에이전트가 성공적으로 업데이트되었습니다.
    • false: 에이전트를 업데이트하지 못했습니다.

    데이터 유형: 부울
    메시지 할당 또는 예외가 성공했음을 확인하는 응답 메시지입니다.

    성공 메시지: 에이전트 구성원 유형 업데이트 요청이 성공적으로 처리되었습니다.

    가능한 예외:
    • 잘못된 요청입니다. 불충분 입력: 에이전트 sys_id 또는 상호작용 sys_id 요청에 제공되지 않았습니다.
    • 제공된 상호작용이 외부 공급업체 상호작용이 아닙니다. 요청은 외부 공급업체 상호작용에 대해서만 작동하며 지정된 요청은 외부 공급업체 상호작용이 아닙니다.
    • 잘못된 요청입니다. 구성원 유형은 [허용된 구성원 유형] 중 하나여야 합니다. 요청에 제공된 구성원 유형은 업데이트할 수 있는 유형 중 하나가 아닙니다.
    • 해당 상호작용에 대한 대화를 찾을 수 없음: 지정된 상호작용 sys_id 있는 해당 대화 기록을 찾을 수 없습니다.
    • 잘못된 요청입니다. 사용자가 제공된 상호작용의 구성원이 아닙니다. 지정된 에이전트 sys_id가 지정된 상호작용 대화의 구성원이 아닙니다.

    데이터 유형: 문자열

    cURL 요청

    다음 요청은 주어진 대화에서 에이전트 사용자를 공개 이행자 역할로 업데이트하는 방법을 보여줍니다.

    curl "https://instance.servicenow.com/api/now/conversation/member/{user_id}/update" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{ 
 \"interaction_id"":\"< interaction_sys_id" >\", 
 \"member_type\":\"public_fulfiller\" 
}" \ 
--user 'username':'password'

    응답은 공개 이행자 역할에 대한 성공적인 업데이트에 대한 정보를 반환합니다. memberType은 업데이트되지만 활성 필드는 true로 유지되며, 이는 에이전트의 유형이 변경되었지만 대화에서 여전히 활성 상태임을 나타냅니다.

    {
  "result": {
    "conversation_member": {
      "active": true,
      "memberType": "public_fulfiller",
      "conversation_id": " <conversation_sys_id>"
    },
    "success": true,
    "message": "Request to update agent member type processed successfully."
  }
}