Session Link

개발자 API

자체 시스템에서 고객 대화로 바로 이동하는 링크를 받으세요. 고객이나 대화가 아직 없으면 생성됩니다.

WhatsApp
Instagram
REST API

MonoStore에서 설치 monochat.ai에서 보기

개요

채널과 고객의 전화번호 또는 이메일을 담은 API 호출 한 번으로, MonoChat에서 해당 고객의 대화를 여는 링크가 반환됩니다. 고객이나 대화가 아직 없으면 생성됩니다.

이 링크를 CRM, 헬프 데스크 또는 주문 화면에 넣으면 팀이 그곳에서 바로 채팅으로 이동할 수 있습니다.

주요 기능

열기 또는 생성. 특정 WhatsApp, Instagram 등 채널의 고객에 대해 전화번호나 이메일로 작동합니다.
호출하면서 바로 배정. 같은 호출에서 대화를 ID나 이메일로 상담원에게, 또는 워크그룹에 배정합니다.
같은 고객, 같은 대화. 같은 고객과 채널로 다시 호출하면 기존 대화가 반환됩니다.

설치 및 설정

설정 › MonoStore › 앱에서 Session Link를 설치하거나 설치 링크 app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA를 여세요. MonoChat 계정이 없다면 링크에서 먼저 가입할 수 있으며, 앱은 자동으로 설치됩니다.
프로필 › API 토큰에서 API 토큰을 만드세요. 토큰은 한 번만 표시되므로 바로 복사해 두세요. API 토큰을 참고하세요.
설정 › Session Link API를 여세요. 그곳의 문서에서 워크스페이스의 정확한 엔드포인트 주소와 바로 복사해 쓸 수 있는 예제 요청을 확인할 수 있습니다. 보유한 채널 중 하나로 예제를 시험해 보세요.
CRM, 헬프 데스크 또는 주문 화면에 API를 호출하고 반환된 url을 여는 "WhatsApp으로 채팅" 버튼을 추가하세요.

노트

이 링크는 로그인되어 있고 해당 대화를 볼 수 있는 권한이 있는 사용자에게 MonoChat을 열어 줍니다.
이 호출은 대화를 열기만 할 뿐 고객에게 메시지를 보내지 않습니다. 먼저 메시지를 보내려면 WhatsApp Template API를 사용하세요.

기능

대화 링크

응답에는 MonoChat에서 대화를 여는 링크와 대화 ID가 포함됩니다.

필요하면 고객 생성

보내 주신 이름과 성으로 새 고객이 생성되며, 응답을 통해 이미 알고 있던 고객인지 알 수 있습니다.

배정

ID나 이메일로 상담원에게, 또는 워크그룹에 배정합니다.

문서 화면

워크스페이스의 정확한 엔드포인트 주소와 바로 복사해 쓸 수 있는 예제 요청이 담긴 API 레퍼런스입니다.

API 레퍼런스

이 호출은 JSON 본문을 담은 POST 요청이며, API 토큰으로 인증합니다.

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

<slug>는 워크스페이스의 테넌트 슬러그로, MonoChat 주소에서 /tenants/ 뒤에 오는 부분입니다.
<app-folder>는 앱이 설치된 폴더입니다. 설정 › Session Link API 화면에서 두 값이 채워진 전체 주소를 확인할 수 있습니다.
토큰은 프로필 › API 토큰에서 만드세요. API 토큰을 참고하세요.

요청 필드

필드	필수	설명
`connectorBrand`	예	채널 유형, 예: `whatsapp` 또는 `instagram`.
`channelUsername`	예	MonoChat에 등록된 채널의 사용자 이름, 예: `+` 없는 WhatsApp 번호.
`customer.identityType`	예	`phoneNumber` 또는 `email`.
`customer.identity`	예	고객의 전화번호(국가 코드 포함, `+` 없음) 또는 이메일 주소.
`customer.firstname`, `customer.lastname`	아니요	고객이 MonoChat에 처음 등록될 때 사용됩니다. 기본값은 `-`.
`assignment.type`	아니요	`agent`(상담원 사용자 ID), `agentIdentity`(상담원 이메일) 또는 `workgroup`(워크그룹 ID).
`assignment.value`	`assignment.type`과 함께	대화를 배정할 ID 또는 이메일.

요청 예시

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

응답

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

필드	설명
`url`	MonoChat에서 대화를 엽니다.
`sessionId`	대화 ID. 같은 채널의 같은 고객은 항상 같은 대화를 받습니다.
`isOldUser`	이 호출로 고객이 생성된 경우 `false`.

오류

호출이 실패하면 오류 상태와 메시지가 반환됩니다.

메시지	원인
`connectorBrand, channelUsername and customer fields are required`	필수 최상위 필드가 누락되었습니다.
`customer.identityType must be one of: phoneNumber, email`	`identityType`이 없거나 다른 값입니다.
`customer.identity field is required`	고객의 전화번호 또는 이메일이 없습니다.
`Channel not found`	워크스페이스에 해당 유형과 사용자 이름의 채널이 없습니다.
`Customer Channel not found`	고객을 채널 ID와 매칭하지 못했습니다.
`Agent user not found`	`assignment.value`에 입력한 이메일의 상담원이 없습니다.
`401`	`Authorization` 헤더가 없거나 토큰이 올바르지 않습니다.