Overview

게임 서버의 길드 소셜을 오픈채팅방에 반영하여 길드전용 채팅방으로 만들고, 그렇게 생성 된 길드 채팅방에 길드 관련 시스템 메시지나 공유메시지를 보낼 수 있는 기능들을 제공합니다.

길드 소셜의 원본데이터는 게임 서버에 존재하므로 게임클라이언트와 연동될 경우 데이터 불일치 문제가 일어날 수 있기 때문에 반드시 서버에서만 호출해야 합니다.

길드채팅에서사용하는프로필이미지스펙

길드 프로필 이미지(imageUrl), 길드장 프로필 이미지(leaderProfileImage), 길드원 프로필 이미지(profileImage)의 요구사항은 다음과 같습니다.

이미지 사이즈: 640*640 (px)
확장자: jpg
API를 통해 url로 전달 시 80(http) or 443(https) 포트로 접근 가능한 url

/guildchat/guild/create

Description

카카오톡에 오픈 채팅방 형태로 길드채팅방을 개설합니다.

용도: 길드장이 길드를 생성 했을 때 혹은 길드 채팅방을 개설하려고 할 때

Method

POST

Request Headers

Name	Type	Mandatory	Description
appId	String	Y	게임 앱 ID
appSecret	String	Y	App Secret
Authorization	String	Y	서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보 KakaoAK {admin_key} 형태의문자열 {admin_key}는 [게임센터 > 게임관리 > 게임세부정보 > Admin Key] 에서확인가능

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
playerId	String	Y	길드를 생성하는 리더 playerId
worldId	Integer	Y	게임 서버 별로 발급 받은 월드 아이디
guildName	String	Y	길드이름 (길드 채팅방 이름으로 설정됨)
leaderNickname	String	Y	길드 채팅방을 개설하는 유저의 게임 닉네임
description	String	N	길드설명 (길드 채팅방 설명으로 설정됨)
leaderProfileImage	String	N	길드 채팅방을 개설하는 유저의 게임프로필 이미지 URL (길드 채팅방의 유저 프로필 이미지로 설정됨, 없을 경우 기본 이미지로 설정됨)
imageUrl	String	N	길드대표이미지 (길드채팅방 대표 프로필 이미지로 설정됨, 없을 경우 기본 이미지로 설정됨)

Response Status Code

Status Code	Status Code 설명	Status Code 상세 설명

Status Code	Status Code 설명	Status Code 상세 설명
200	정상 응답	정상
400	Bad Request	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류
401	Unauthenticated	인증 실패
403	Forbidden	요청 헤더와 파라미터 각각의 앱 아이디가 일치하지 않는 경우 또는 카카오 오픈채팅 약관동의가 안 된 사용자가 채팅방 생성을 요청하는 경우 (참고: 카카오톡에서 반환하는 HTTP Code를 그대로 매칭해서 반환)
406	Not Acceptable	요청한 길드아이디와 동일한 길드아이디가 존재하는 경우 또는 카카오 앱 유저 아이디를 조회할 수 없는 경우
412	Precondition Failed	앱 도메인 아이디가 미 등록된 경우
500	Internal Server Error	서버 시스템 내부 오류
503	Service Unavailable	서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name	Type	Description

Name	Type	Description
worldId	Integer	게임 서버 별로 발급 받은 월드 아이디
guildId	Integer	생성 된 길드 채팅방 아이디

Example Request

POST /service/v3/guildchat/guild/create HTTP/1.1
Host: openapi-zinny3.game.kakao.com:10443
appId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
Content-Type: application/json;charset=UTF-8
Authorization: KakaoAK c0948035a320f789f585acae3dedcd70
  
{
    "playerId": "797921915636",
    "worldId": 33040,
    "guildName": "테스트 길드",
    "leaderNickname": "레오짱",
    "leaderProfileImage": "http://mud-kage.kakao.co.kr/dn/LmBIG/wkpVjrqFKE/8YZ8etC5X4TfNqdxkHuxFk/img.jpg",
    "description": "레오길드입니다",
    "imageUrl": "http://mud-kage.kakao.co.kr/dn/LmBIG/wkpVjrqFKE/8YZ8etC5X4TfNqdxkHuxFk/img.jpg"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "worldId": 33040,
    "guildId": 1104
}

/guildchat/guild/update

Description

길드 채팅방 이름, 프로필 이미지 등을 변경합니다.

Method

POST

Request Headers

Name	Type	Mandatory	Description
appId	String	Y	게임 앱 ID
appSecret	String	Y	App Secret
Authorization	String	Y	서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보 KakaoAK {admin_key} 형태의문자열 {admin_key}는 [게임센터 > 게임관리 > 게임세부정보 > Admin Key] 에서확인가능

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
playerId	String	Y	현재 리더 playerId
worldId	Integer	Y	게임 서버 별로 발급 받은 월드 아이디
guildId	Integer	Y	길드 채팅방 아이디
guildName	String	N	길드이름 (길드 채팅방 이름으로 설정됨)
newLeaderId	String	N	변경할 길드장 Player ID
description	String	N	길드설명 (길드 채팅방 설명으로 설정됨)
imageUrl	String	N	길드대표이미지 (길드채팅방 대표 프로필 이미지로 설정됨, 없을 경우 기본 이미지로 설정됨)

Response Status Code

Status Code	Status Code 설명	Status Code 상세 설명

Status Code	Status Code 설명	Status Code 상세 설명
200	정상 응답	정상
400	Bad Request	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류
401	Unauthenticated	인증 실패
403	Forbidden	요청 헤더와 파라미터 각각의 앱 아이디가 일치하지 않는 경우 또는 카카오 오픈채팅 약관동의가 안 된 사용자가 채팅방 생성을 요청하는 경우 (참고: 카카오톡에서 반환하는 HTTP Code를 그대로 매칭해서 반환)
406	Not Acceptable	요청한 길드아이디가 존재하지 않는 경우 또는 카카오 앱 유저 아이디를 조회할 수 없는 경우
500	Internal Server Error	서버 시스템 내부 오류
503	Service Unavailable	서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name	Type	Description

Name	Type	Description

Example Request

POST /service/v3/guildchat/guild/update HTTP/1.1
Host: openapi-zinny3.game.kakao.com:10443
appId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
Content-Type: application/json;charset=UTF-8
Authorization: KakaoAK c0948035a320f789f585acae3dedcd70
  
{
    "playerId": "797921915636",
    "worldId": 33040,
    "guildId": 1104,
    "guildName": "테스트 길드2",
    "description": "레오길드 설명 수정했습니다.",
    "imageUrl": "http://mud-kage.kakao.co.kr/dn/LmBIG/wkpVjrqFKE/8YZ8etC5X4TfNqdxkHuxFk/img.jpg"
}

Example Response

/guildchat/guild/delete

Description

길드채팅방을 삭제합니다.

Method

POST

Request Headers

Name	Type	Mandatory	Description
appId	String	Y	게임 앱 ID
appSecret	String	Y	App Secret
Authorization	String	Y	서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보 KakaoAK {admin_key} 형태의문자열 {admin_key}는 [게임센터 > 게임관리 > 게임세부정보 > Admin Key] 에서확인가능

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
worldId	Integer	Y	게임 서버 별로 발급 받은 월드 아이디
guildId	Integer	Y	길드 채팅방 아이디

Response Status Code

Status Code	Status Code 설명	Status Code 상세 설명

Status Code	Status Code 설명	Status Code 상세 설명
200	정상 응답	정상
400	Bad Request	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류
401	Unauthenticated	인증 실패
403	Forbidden	요청 헤더와 파라미터 각각의 앱 아이디가 일치하지 않는 경우 또는 카카오 오픈채팅 약관동의가 안 된 사용자가 채팅방 삭제를 요청하는 경우 (참고: 카카오톡에서 반환하는 HTTP Code를 그대로 매칭해서 반환)
406	Not Acceptable	요청한 길드아이디가 존재하지 않는 경우 또는 요청한 플레이어가 해당 길드채팅방의 방장이 아닌 경우 또는 카카오 앱 유저 아이디를 조회할 수 없는 경우
500	Internal Server Error	서버 시스템 내부 오류
503	Service Unavailable	서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name	Type	Description

Name	Type	Description

Example Request

Example Response

/guildchat/member/join

Description

길드 채팅방에 새로운 Player를 참여시킵니다.

Method

POST

Request Headers

Name	Type	Mandatory	Description
appId	String	Y	게임 앱 ID
appSecret	String	Y	App Secret
Authorization	String	Y	서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보 KakaoAK {admin_key} 형태의문자열 {admin_key}는 [게임센터 > 게임관리 > 게임세부정보 > Admin Key] 에서확인가능

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
playerId	String	Y	길드 채팅방에 새로 참여하는 playerId
worldId	Integer	Y	게임 서버 별로 발급 받은 월드 아이디
guildId	Integer	Y	길드 채팅방 아이디
nickname	String	Y	참여자 닉네임
imageUrl	String	N	참여자 프로필 이미지

Response Status Code

Status Code	Status Code 설명	Status Code 상세 설명

Status Code	Status Code 설명	Status Code 상세 설명
200	정상 응답	정상
400	Bad Request	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류
401	Unauthenticated	인증 실패
403	Forbidden	요청 헤더와 파라미터 각각의 앱 아이디가 일치하지 않는 경우 또는 카카오 오픈채팅 약관동의가 안 된 사용자가 채팅방 가입을 요청하는 경우 (참고: 카카오톡에서 반환하는 HTTP Code를 그대로 매칭해서 반환)
406	Not Acceptable	요청한 길드아이디가 존재하지 않는 경우 또는 카카오 앱 유저 아이디를 조회할 수 없는 경우
500	Internal Server Error	서버 시스템 내부 오류
503	Service Unavailable	서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name	Type	Description

Name	Type	Description
userId	Long	길드 채팅방에 새로 참여한 유저의 카카오 게임 회원번호 (Capri User ID)

Example Request

Example Response

/guildchat/member/leave

Description

길드 채팅방에서 멤버가 탈퇴하면서 채팅방에서 나가게 됩니다.

마지막 멤버가 나갈때에는 길드까지 자동으로 삭제 처리 됩니다.

Method

POST

Request Headers

Name	Type	Mandatory	Description
appId	String	Y	게임 앱 ID
appSecret	String	Y	App Secret
Authorization	String	Y	서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보 KakaoAK {admin_key} 형태의문자열 {admin_key}는 [게임센터 > 게임관리 > 게임세부정보 > Admin Key] 에서확인가능

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
playerId	String	Y	길드 채팅방을 나가는 playerId
worldId	Integer	Y	게임 서버 별로 발급 받은 월드 아이디
guildId	Integer	Y	길드 채팅방 아이디

Response Status Code

Status Code	Status Code 설명	Status Code 상세 설명

Status Code	Status Code 설명	Status Code 상세 설명
200	정상 응답	정상
400	Bad Request	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류
401	Unauthenticated	인증 실패
403	Forbidden	요청 헤더와 파라미터 각각의 앱 아이디가 일치하지 않는 경우 또는 카카오 오픈채팅 약관동의가 안 된 사용자가 채팅방 생성을 요청하는 경우 (참고: 카카오톡에서 반환하는 HTTP Code를 그대로 매칭해서 반환)
406	Not Acceptable	요청한 플레이어 아이디가 해당 길드채팅방에 존재하지 않는 경우 또는 요청한 플레이어 아이디가 해당 길드채팅방의 방장인 경우 또는 카카오 앱 유저 아이디를 조회할 수 없는 경우
500	Internal Server Error	서버 시스템 내부 오류
503	Service Unavailable	서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name	Type	Description

Name	Type	Description

Example Request

Example Response

/guildchat/member/updateProfile

Description

길드 채팅방에 참여한 유저의 채팅방 내의 닉네임이나 프로필 사진을 변경 합니다.

Method

POST

Request Headers

Name	Type	Mandatory	Description
appId	String	Y	게임 앱 ID
appSecret	String	Y	App Secret
Authorization	String	Y	서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보 KakaoAK {admin_key} 형태의문자열 {admin_key}는 [게임센터 > 게임관리 > 게임세부정보 > Admin Key] 에서확인가능

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
playerId	String	Y	프로필 업데이트할 playerId
worldId	Integer	Y	게임 서버 별로 발급 받은 월드 아이디
guildId	Integer	Y	길드 채팅방 아이디
nickname	String	Y	닉네임
imageUrl	String	N	프로필 이미지

Response Status Code

Status Code	Status Code 설명	Status Code 상세 설명

Status Code	Status Code 설명	Status Code 상세 설명
200	정상 응답	정상
400	Bad Request	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류
401	Unauthenticated	인증 실패
406	Not Acceptable	처리 불가
500	Internal Server Error	서버 시스템 내부 오류
503	Service Unavailable	서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name	Type	Description

Name	Type	Description

Example Request

Example Response

/guildchat/chat/sendFeed

Description

길드 채팅방에 피드 형태의 메시지를 전송합니다.

API를 통해 직접 전송하며, 메시지 템플릿을 사전에 등록할 필요가 없습니다.

Method

POST

Request Headers

Name	Type	Mandatory	Description
appId	String	Y	게임 앱 ID
appSecret	String	Y	App Secret
Authorization	String	Y	서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보 KakaoAK {admin_key} 형태의문자열 {admin_key}는 [게임센터 > 게임관리 > 게임세부정보 > Admin Key] 에서확인가능

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
worldId	Integer	Y	게임 서버 별로 발급 받은 월드 아이디
guildId	Integer	Y	길드 채팅방 아이디
icon	String	Y	피드 좌측에 표시되는 아이콘이미지 URL 아이콘사이즈는 60*60
text	String	Y	피드에 표시할 메시지 카카오톡 클라이언트에서 최대 두 줄로 표시되며 초과할 경우 말줄임표(…)로 표시 일부 텍스트 강조를 위해 font style 지원. 최대 1회 1연결 단어에 대해서만 사용하고 강조 컬러는 #feef46만 사용 가능 예시: OOO님이 <font color="#feef46">희귀아이템</font>을 획득 하셨습니다.
type	String	N	피드링크타입 (없을 경우, app으로 설정됨) web: 웹브라우저로 url 연결 app: 게임앱실행. 이 경우 url과 install url 정보를 자동으로 심어줌 (게임센터에서 입력한 정보 참조)
webUrl	String	N	이동할 링크 url (type=web일 경우 필수)

Response Status Code

Status Code	Status Code 설명	Status Code 상세 설명

Status Code	Status Code 설명	Status Code 상세 설명
200	정상 응답	정상
400	Bad Request	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류
401	Unauthenticated	인증 실패
406	Not Acceptable	처리 불가
500	Internal Server Error	서버 시스템 내부 오류
503	Service Unavailable	서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name	Type	Description

Name	Type	Description

28.2. Server API 예제 (/guildchat)

Overview

/guildchat/guild/create

Description

Method

Request Headers

Request Body Parameters

Response Status Code

Response Content

Example Request

Example Response

/guildchat/guild/update

Description

Method

Request Headers

Request Body Parameters

Response Status Code

Response Content

Example Request

Example Response

/guildchat/guild/delete

Description

Method

Request Headers

Request Body Parameters

Response Status Code

Response Content

Example Request

Example Response

/guildchat/member/join

Description

Method

Request Headers

Request Body Parameters

Response Content

Example Request

Example Response

/guildchat/member/leave

Description

Method

Request Headers

Request Body Parameters

Response Status Code

Response Content

Example Request

Example Response

/guildchat/member/updateProfile

Description

Method

Request Headers

Request Body Parameters

Response Content

Example Request

Example Response

/guildchat/chat/sendFeed

Description

Method

Request Headers

Request Body Parameters

Response Content

Example Request

Example Response