8. 회사 홈페이지에 넣기

고객이 회사 홈페이지에서 바로 상담원을 골라 원격 지원 연결을 요청하게 합니다. 기업 지원 페이지(4장의 관리 센터 설정)를 켠 회사가 씁니다.

상담원의 수락과 고객의 동의는 지금처럼 그대로 거칩니다. 홈페이지는 연결을 요청할 뿐, 연결을 만들지 않습니다.

먼저 사이트를 등록합니다

관리 센터의 원격 지원 > 기업 지원 페이지에서 다른 사이트에서 사용에 홈페이지 주소를 한 줄에 하나씩 10개까지 넣고 저장합니다. https로 시작하는 주소를 경로 없이 씁니다(예: https://www.example.com). 개발할 때는 http://localhost:3000처럼 쓸 수 있습니다.

위젯과 상담원 목록은 등록한 사이트에서만 보이고, 공개 API도 브라우저에서는 등록한 사이트에서만 부를 수 있습니다. 저장하면 그 아래에 회사의 페이지 주소가 들어간 코드가 보이므로 그대로 복사해 씁니다.

홈페이지에 다음 한 줄을 붙여 넣으면 화면 오른쪽 아래에 "원격 지원" 단추가 뜹니다. 고객이 상담원을 고르면 그 자리에서 접속번호, 원격 지원 프로그램 받기, 상담원의 수락 여부를 봅니다.

<script src="https://officeview.co.kr/help/widget/v1.js" data-page="페이지 주소" async></script>

단추 대신 정한 자리에 보이려면 그 자리에 다음 요소를 둡니다. 바탕이 어두우면 script에 data-theme="dark"를 더합니다.

<div data-officeview-help></div>

방법 2. 상담원 목록 넣기

위젯 대신 상담원 목록 화면을 그대로 넣습니다. 목록 화면은 등록한 사이트 안에서만 보입니다.

<iframe src="https://officeview.co.kr/help/페이지 주소/embed" title="원격 지원"
        width="480" height="560" style="border:0;max-width:100%"></iframe>

바탕이 어두우면 주소 끝에 ?theme=dark를 붙입니다.

방법 3. 공개 API로 직접 그리기

홈페이지의 화면은 회사가 직접 만들고, 상담원 목록과 연결 요청은 공개 API로 주고받습니다.

기본 주소: https://officeview.co.kr/api/help/v1/pages/{페이지 주소}
브라우저에서는 등록한 사이트에서만 부를 수 있습니다(CORS). 쿠키는 쓰지 않습니다.
고객의 브라우저에서 부릅니다. 횟수와 기다리는 요청을 방문자의 주소마다 세므로, 회사 서버를 거쳐 부르면 모든 고객이 한도 하나를 나눠 씁니다.
보내는 본문은 JSON입니다(Content-Type: application/json). 다른 요청 헤더는 더하지 않습니다(브라우저의 사전 요청에서 막힙니다).
v1 안에서는 응답에 필드를 더하기만 합니다. 모르는 필드는 무시하면 됩니다.

상담원 목록

GET /api/help/v1/pages/{페이지 주소}

필드	뜻
`slug`	페이지 주소
`company`	회사 이름
`logoUrl`	로고 그림의 주소, 로고가 없으면 `null`
`agents[].id`	상담원을 가리키는 값(연결 요청에 그대로 보냅니다)
`agents[].name`	회사가 정한 상담원의 공개 이름

목록에는 회사가 보이기로 한 상담원 가운데 지금 상담원 프로그램에 로그인해 있고 고객을 더 맡을 수 있는 상담원만 나옵니다.

연결 요청

POST /api/help/v1/pages/{페이지 주소}/requests
{"agent": "상담원의 id"}

필드	뜻
`token`	이 요청의 토큰: 형편 묻기와 취소에 보냅니다
`code`	접속번호(6자리)
`state`	요청의 형편(아래 표)
`expiresAt`	상담원이 답해야 하는 때: 요청한 뒤 3분(ISO 8601, UTC)
`company`, `agent`	회사 이름, 고른 상담원의 공개 이름
`downloadUrl`	접속번호가 이름에 붙은 원격 지원 프로그램: 고객이 누르는 링크로 둡니다(`pending`과 `accepted` 동안만 받을 수 있고, 그 뒤는 410)
`pageUrl`	OfficeView의 요청 화면(새 창으로 열 때)

형편 묻기와 취소

POST /api/help/v1/pages/{페이지 주소}/requests/state   {"token": "..."}
POST /api/help/v1/pages/{페이지 주소}/requests/cancel  {"token": "..."}

답은 연결 요청의 답과 같은 필드입니다. 3초마다 형편을 묻고, 연결된 뒤에는 10초마다 물으면 충분합니다. 끝난 형편이면 그만 묻습니다. 취소는 상담원이 아직 답하지 않은 요청만 거둡니다.

`state`	뜻
`pending`	상담원의 수락을 기다립니다
`accepted`	상담원이 수락했습니다: 받은 프로그램을 실행하면 동의 화면이 나옵니다
`joined`	프로그램이 상담원에게 닿았고 고객의 동의를 기다립니다
`connected`	연결되었습니다
`ended`	연결이 끝났습니다(끝난 형편)
`declined`	상담원이 거절했습니다(끝난 형편)
`expired`	상담원이 답하지 않아 시간이 지났습니다(끝난 형편)
`cancelled`	고객이 취소했습니다(끝난 형편)

오류

오류의 답은 {"code": "...", "message": "..."}입니다. 415만 이 모양이 아닙니다.

상태	`code`	뜻
400	`invalid_body`, `invalid_agent`	본문이 JSON이 아니거나 상담원 값이 틀렸습니다
403	`origin_not_allowed`	등록하지 않은 사이트에서 불렀습니다(브라우저에서는 CORS 오류로 보입니다)
404	`page_not_found`, `request_not_found`	페이지가 없거나 꺼졌습니다, 또는 모르는 토큰입니다
409	`agent_unavailable`	그 상담원이 지금 요청을 받을 수 없습니다
409	`request_open`	같은 네트워크에서 낸 요청이 아직 기다리고 있습니다
415	-	본문의 `Content-Type`이 `application/json`이 아닙니다
429	`too_many_requests`	횟수를 넘었거나 회사의 기다리는 요청이 너무 많습니다: `Retry-After`(초) 뒤에 다시 합니다
503	`unavailable`	잠시 쓸 수 없습니다

방문자의 주소마다 15분 동안 연결 요청 10번, 형편 묻기 600번, 목록 읽기 300번까지이며, 연결 요청과 형편 묻기는 기업 지원 페이지에서 한 것과 함께 셉니다. 회사마다는 15분 동안 연결 요청 120번, 한 번에 기다리는 요청 50개까지입니다.

예제

const api = 'https://officeview.co.kr/api/help/v1/pages/페이지 주소';
async function call(url, body) {
  const init = body === undefined ? {} : {
    method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(body)
  };
  const r = await fetch(url, init);
  const json = await r.json();
  if (!r.ok) throw new Error(json.code);   // 오류 표의 code
  return json;
}

const page = await call(api);   // page.agents 를 회사 화면에 그립니다
const request = await call(api + '/requests', {agent: page.agents[0].id});
// request.code 를 보이고, request.downloadUrl 을 '원격 지원 프로그램 받기' 링크로 둡니다
const timer = setInterval(async function () {
  const now = await call(api + '/requests/state', {token: request.token});
  if (['ended', 'declined', 'expired', 'cancelled'].includes(now.state)) clearInterval(timer);
}, 3000);

홈페이지가 CSP를 쓰면

위젯은 script-src, style-src, img-src, connect-src에, 상담원 목록 넣기는 frame-src에 https://officeview.co.kr를 더합니다. 공개 API만 쓰면 connect-src와(로고를 보이면) img-src에 더합니다.

알아 둘 것

토큰은 그 요청을 낸 고객의 것입니다. 다른 사람에게 보이거나 서버에 오래 두지 않습니다.
원격 지원 이용권이 없거나 기업 지원 페이지를 끄면 공개 API와 상담원 목록 넣기는 없는 페이지(404)가 되고, 위젯은 "지금은 원격 지원 페이지를 열 수 없습니다."를 보입니다.
등록하지 않은 사이트에서 위젯을 열면 브라우저 콘솔에 사이트를 등록하라는 경고가 남습니다.
사이트 등록을 지우면 그 사이트에서는 곧바로(늦어도 10초 안에) 동작하지 않습니다.