SMS API

Contact Center AI Platform (CCAI Platform)을 사용하면 SMS API를 사용하여 수신 및 발신 SMS 메시지를 처리할 수 있습니다.

인증

SMS API를 사용하려면 사용자 인증 정보가 필요합니다.

SMS API의 사용자 인증 정보를 만들려면 다음 단계를 따르세요.

  1. CCAI Platform 포털에서 설정 > 개발자 설정 > API 사용자 인증 정보 관리를 클릭합니다.

  2. + API 사용자 인증 정보 추가 버튼을 클릭합니다. API 사용자 인증 정보 추가 메시지가 열립니다.

  3. 사용자 인증 정보의 이름을 입력합니다.

  4. 만들기를 클릭합니다.

아웃바운드 SMS API

아웃바운드 SMS API는 아웃바운드 SMS 메시지를 시작하기 위한 엔드포인트를 제공합니다. 이를 통해 프로그래매틱 방식으로 소비자에게 SMS 메시지를 보낼 수 있습니다.

이 API를 사용할 때 고려해야 할 세 가지 주요 사항이 있습니다.

  • 이 서비스는 한 번에 수만 개의 메시지를 전송하도록 설계되지 않았습니다. 목표는 이벤트 기반 메시지입니다.

  • 소비자는 SMS 메시지에 응답하여 지원 세션을 시작할 수 있습니다.

  • 같은 날에 동일한 번호로 여러 SMS 메시지를 보내야 하는 경우 이 API는 작동하지 않습니다.

사용 사례

아웃바운드 SMS API 샘플 사용 사례는 이벤트 기반입니다. 예를 들어 소비자에게 주문이 수령 준비되었음을 알리고 응답 옵션을 제공하려는 경우입니다. 아웃바운드 SMS가 전송되면 활성 세션이 생성됩니다. 고객이 응답하면 상담사에게 라우팅됩니다.

이 API와 세션 없는 아웃바운드 SMS API의 차이점은 세션이 없는 경우 알림만 전송하고 소비자가 응답하면 기본 메시지 (구성된 경우)를 수신하며 상담사에게 라우팅되지 않는다는 것입니다.

기타 잠재적 사용 사례:

  • 계정 로그인
  • 계정 활동을 클릭합니다.
  • 중요한 계정 사용 이벤트입니다.
  • 연결된 기기 문제 감지
  • 배송 및 차량 공유와 같은 주문형 서비스의 도착 예정 시간 알림
  • 일정 알림
  • 사전 대응 서비스 또는 계정 알림
  • 2단계 인증 (고객에게 기존 코드 생성기 및 서비스 프로세스가 있어야 함)

아웃바운드 SMS API 엔드포인트

이 새 엔드포인트의 기본 URI는 다음과 같습니다.

POST https://<subdomain>.<domain>/apps/api/v1/sms

인바운드 SMS 지원

환경에서 인바운드 SMS 응답을 지원하려면 아웃바운드 번호도 대기열에 할당된 인바운드 SMS 번호로 설정해야 합니다. 각 SMS 전화번호는 하나의 대기열에만 할당할 수 있습니다. 자세한 내용은 일반 SMS 채팅 구성을 참고하세요.

최종 사용자가 이러한 방식으로 구성된 SMS에 답장하면 인바운드 SMS 전화번호가 할당된 SMS 대기열 메뉴로 이동합니다. 자세한 내용은 SMS 메시지 채팅 설정 - 전화번호를 참고하세요.

API 작업

이 섹션에서는 API 작업, 본문 매개변수, 응답 코드를 간략하게 설명합니다.

본문 및 파라미터

API 요청 본문에는 다음 필드가 포함되어야 합니다.

필드 이름 유형 필수 설명 값 참고
agent_id 정수 아니요 제공된 번호 간에 채팅이 없는 경우 이 ID에 해당하는 상담사가 새 채팅에 할당됩니다. 상담사가 기존 채팅에 연결되어 있으면 상담사를 대신하여 메시지가 전송됩니다.
agent_email 문자열 아니요 상담사의 이메일 주소입니다.
chat_type 문자열 예 SMS 메시지 SMSAP
chat_subtype 문자열 예 api_initiated
end_user_number 문자열 예 SMS를 전송할 번호 유효성 검사: 유효한 전화번호: 미국 전화번호의 경우 +18882468888
outbound_number 문자열 예 SMS 메시지를 전송하는 데 사용할 발신 전화번호 유효성 검사: a) 전화번호가 테넌트와 연결된 SMS 전화번호여야 함, b) 전화번호가 누락됨, c) 전화번호 형식이 잘못됨(미국 전화번호의 경우 +18882468888)
메시지 문자열 예 소비자에게 전송할 SMS 메시지 긴 메시지: 긴 메시지를 여러 메시지로 분할합니다 (기존 아웃바운드 SMS 기능에 포함되어야 함). 유효성 검사: a) 메시지 누락, b) 메시지가 최대 글자 수 (x)를 초과함
ticket_id id 아니요 세션을 특정 CRM 티켓 ID와 연결합니다. 참고: 잘못된 티켓 ID는 무시됩니다.

오류 및 성공

케이스 예상 결과 복사
SMS 서비스가 사용 설정됨
아웃바운드 SMS 서비스가 사용 설정됨
chat_type 값이 'OutboundSMSAPI'임
end_user_number가 제공되고 형식이 올바름
outbound_number가 제공되고 형식이 올바름
미국 외 전화번호의 경우: 미국 외 전화번호가 사용 설정됨
메시지가 제공됨
outbound_number와 end_user_number 간에 활성 채팅이 없음		 성공 (200) 성공 응답 샘플
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
상담사 ID와 상담사 이메일이 제공됩니다. 오류 agent_id 또는 agent_email 중 하나만 제공할 수 있습니다.
상담사 ID 또는 상담사 이메일이 제공됨
상담사가 기존 채팅에 연결되지 않음		 오류 아웃바운드 SMS가 실패했습니다. 상담사가 채팅에 연결되어 있지 않습니다.
SMS 서비스가 사용 설정되지 않음 오류 'SMS 서비스가 사용 설정되지 않음'
아웃바운드 SMS 서비스가 사용 설정되지 않음 오류 '아웃바운드 SMS 서비스가 사용 설정되지 않음'
chat_type이 제공되지 않음 오류 'chat_type을 제공해야 합니다'
chat_type이 제공되었지만 'sms'로 설정되지 않음 오류 '유효한 chat_type을 제공해야 합니다'
end_user_number가 제공되었지만 형식이 올바르지 않음 오류 'end_user_number가 잘못됨'
(참고: 미국 전화번호의 경우 유효한 전화번호는 '+18882468888'임)
end_user_number가 제공되지 않음 오류 'end_user_number is required'
outbound_number가 제공되었지만 형식이 올바르지 않음 오류 'outbound_number가 잘못됨'
(참고: 미국 전화번호의 경우 유효한 전화번호는 '+18882468888'임)
outbound_number가 제공되었지만 해당 테넌트에 존재하지 않음 오류 'outbound_number를 찾을 수 없음'
outbound_number가 제공되지 않음 오류 'outbound_number is required'
outbound_number가 미국 외 전화번호이고 '미국 외 전화번호 서비스'가 사용 설정되어 있지 않음 오류 '미국 외 전화번호 서비스가 사용 설정되지 않음'
참고: 설정 > 통화 중 SMS > 미국 외 전화번호 구성의 미국 외 전화번호 설정에 따라 달라집니다.
메시지가 비어 있음 오류 'message is required'
outbound_number와 end_user_number 간의 활성 채팅 오류 '아웃바운드 SMS가 실패했습니다. 소비자가 이미 활성 SMS 세션에 있습니다.'
ticket_id가 입력되었지만 CRM에 존재하지 않음 오류 '티켓을 찾을 수 없음'

SMS 만료

발신 SMS 메시지는 전송되는 즉시 활성화됩니다.

특정 아웃바운드 및 소비자 전화번호 간에 새 SMS 채팅 세션을 설정하려면 먼저 SMS 채팅을 종료해야 합니다. 여기에는 API를 사용하여 전송된 아웃바운드 SMS 메시지가 포함됩니다. 발신 전화번호와 소비자 전화번호 간에 기존의 활성 채팅이 있는 경우 발신 SMS가 실패합니다.

자동 채팅 제한 시간 옵션

자동 채팅 시간 제한 옵션은 설정 > 채팅 > SMS 만료 및 전역 시간 제한에서 구성됩니다. 채팅 세션 흐름에 활동이나 진행 상황이 없는 경우 채팅 세션이 활성 상태로 유지되는 시간을 제어합니다.

채팅 상태 구분

다음은 채팅 프로세스 상태 변경 간의 차이점입니다.

  • 대기열 선택 상태 Chat ExpirationAPI를 사용하여 전송된 아웃바운드 채팅은 고객이 답장할 때까지 대기열 선택 상태로 간주됩니다.

    대기열 선택 상태를 벗어나지 않은 채팅 세션입니다. 여기에는 소비자가 답장하지 않은 발신 SMS 메시지가 포함됩니다. 채팅이 만료되기 전에 이 상태로 유지될 수 있는 시간을 정의할 수 있습니다 (메시지가 전송되고 타이머 내에 소비자가 응답하지 않으면 채팅이 만료됨).

  • 응답하지 않은 SMS 채팅 만료 (영업시간 중)특정 대기열의 설정된 영업시간 내에 채팅이 만료되기 전에 대기열에서 응답하지 않은 상태로 유지될 수 있는 시간입니다.

  • 응답되지 않은 SMS 채팅 만료 (근무 시간 외)특정 대기열의 설정된 운영 시간 외에 채팅이 만료되기 전에 대기열에서 응답되지 않은 상태로 유지될 수 있는 시간입니다.

  • 아웃바운드 SMS 채팅 시간 제한 [x] 분 동안 활동이 없으면 아웃바운드 SMS 채팅 세션이 자동으로 만료됩니다.

채팅 상태 세부정보

  • API를 사용하여 아웃바운드 SMS를 전송하면 채팅이 활성으로 간주되지만 연결됨으로 간주되지는 않습니다.

  • 이러한 활성 아웃바운드 SMS 채팅은 소비자가 답장할 때까지 대기열 선택 상태로 간주됩니다.

  • 소비자가 답장하고 상담사가 채팅에 할당되면 채팅이 연결됨으로 간주됩니다.

채팅 상태가 적용된 타이머에 미치는 영향

  • API를 사용하여 전송되었으며 소비자로부터 응답을 받지 못한 활성 채팅에는 대기열 선택 상태 타이머가 적용됩니다.

  • 상담사에게 연결된 채팅에는 아웃바운드 만료 타이머가 적용됩니다.

  • 소비자가 초기 메시지에 답장했지만 상담사가 할당되지 않은 경우 채팅이 연결되지 않으며 운영 시간 내 또는 후에 미응답 채팅 만료 타이머가 적용됩니다.

API 메시지 흐름 및 상태의 예:

  1. API를 사용하여 소비자에게 SMS 메시지가 전송됨 - 채팅이 대기열 선택 상태에 있으며 상담사와 연결되지 않음

  2. 대기열 선택 상태 채팅 만료 타이머가 시작됩니다. 소비자가 타이머 기준 시간 내에 응답하지 않으면 채팅이 타임아웃되고 종료됩니다.

  3. 소비자가 채팅에 답장함 - 이제 채팅이 상담사에게 연결됨

  4. 소비자가 마지막 메시지를 보냅니다. 발신 SMS 채팅 제한 시간 타이머가 시작됩니다.

  5. 발신 SMS 채팅 제한 시간 타이머 기준에 도달하여 채팅이 종료되었습니다.

채팅 종료 타이머 없음 - API에서 시작된 아웃바운드 SMS 세션의 경우 채팅 종료 타이머가 작동하지 않으므로 소비자가 메시지에 답장할 때 해당 채팅이 인바운드 채팅으로 들어온 후에도 채팅 종료 이벤트가 발생하지 않습니다.

응답 정의

API는 /calls의 모델에서 볼 수 있듯이 단일 통화 객체로 응답합니다.

세션 없는 아웃바운드 SMS API

CCAI Platform은 연결된 세션 없이 아웃바운드 SMS 메시지를 지원할 수 있는 아웃바운드 SMS API를 제공합니다.

이 API 호출은 CCAI Platform을 사용하여 기존 워크플로 중에 트리거될 수 있는 세션 연결되지 않은 SMS 메시지를 시작합니다.

세션이 없는 SMS는 소비자에게 일회성 메시지만 전송되고 CRM 티켓을 열 필요가 없는 경우에 사용하는 것이 좋습니다.

이 아웃바운드 SMS API는 API 호출당 최대 500개의 메시지를 전송하는 기능을 제공합니다.

사용 사례

세션이 없는 SMS의 일반적인 사용 사례는 다음과 같습니다.

  • 일회용 비밀번호 설정

  • 인증 코드

  • 일정 알림

  • 의견 링크

  • 마케팅 또는 프로모션 메시지

세션이 없는 아웃바운드 API와 아웃바운드 SMS API는 소비자가 응답할 때 활성 세션이 시작되고 상담사에게 라우팅될 수 있다는 점에서 다릅니다. 사용 사례 (배송 알림, 약속 알림)는 비슷하지만 소비자가 응답할 때 발생하는 상황이 다릅니다. 세션이 없는 경우 기본 회신 금지 알림을 받을 수 있지만 아웃바운드 SMS의 경우 상담사에게 라우팅됩니다.

세션 없는 아웃바운드 SMS API 엔드포인트

이 엔드포인트의 기본 URI는 다음과 같습니다.

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

API 사용자 인증 정보 추가

  1. CCAI Platform 포털에서 설정 > 개발자 설정 > API 사용자 인증 정보 관리로 이동합니다.

  2. + API 사용자 인증 정보 추가 버튼을 클릭합니다. API 사용자 인증 정보 추가 메시지가 열립니다.

  3. 사용자 인증 정보 이름을 입력합니다.

  4. 만들기를 클릭합니다.

SMS 메시지 보내기

세션이 없는 아웃바운드 SMS를 보내려면 POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms를 호출하고 다음 요청 매개변수를 전달합니다.

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
필드 이름 유형 필수 설명 참고
from_phone 문자열 예 메시지가 전송될 전화번호입니다. 유효한 미국 번호여야 합니다.
다음과 같은 경우 API 호출에서 오류가 반환됩니다.
* 전화번호가 테넌트와 연결된 SMS 전화번호가 아님
* from_phone 필드가 비어 있음
* 전화번호가 올바른 형식을 따르지 않음 예를 들어 다음 번호는 유효한 미국 전화번호입니다. +18882468888
to_phones 배열 [문자열] 예 메시지를 보낼 전화번호입니다. API 호출이 성공하려면 다음을 확인하세요.
* 유효한 전화번호가 있는지 확인합니다(예:+18882468888). API 호출당 최대 전화번호 수는 100개입니다.
메시지 배열 [문자열] 예 전송할 메시지입니다. 보낼 수 있는 별도의 메시지 최대 개수는 5개입니다.
각 메시지는 320자(영문 기준)를 초과할 수 없습니다.

API 응답

API 호출이 성공하면 다음이 표시됩니다.

  • code: 200

  • 요청 ID

    시스템 기록에 요청 ID를 로깅해야 합니다. 문제를 해결해야 하는 경우 지원팀에서 지원을 제공하려면 요청 ID가 필요합니다.

API 호출이 실패하면 다음이 표시됩니다.

  • code: 4xx

  • 오류 메시지

SMS 제한사항

  • API는 분당 최대 300개의 메시지를 처리합니다.

  • 처리되지 않은 모든 메시지는 2시간 후에 만료됩니다.