---
title: Direct Message 보내기 API
slug: world-sdk-guide-kr/direct-message-api
docTags:
createdAt: 2024-09-02T08:34:13.135Z
---
ZEPETO 월드 내에서 다른 사용자에게 직접 메시지를 보내려면 Send Direct Message(DM) API를 사용하세요.
출시된 월드에서 Direct Message (DM) 전송 API를 사용할 때, 메시지 하단에 월드에 들어갈 수 있는 링크가 자동으로 제공되어 월드를 홍보하는 데 좋습니다.
사용 시 주의사항을 반드시 준수해 주세요.
## 설치
Window → Package Manager → ZEPETO.World 패키지를 먼저 버전 1.21.14 이상으로 설치해 주세요.
그 후, 버전 1.0.7 이상인 ‘ZEPETO.Module’ 패키지를 설치해 주세요.
ZEPETO 앱이 버전 3.46.000 이상으로 실행되고 있는지 확인해 주세요.
## 직접 메시지 전송 API
- Send DM API를 사용하려면 아래의 import 문을 추가하세요.
```typescript
import { SocialService } from 'ZEPETO.Module.Social';
```
### DM 전송 핵심 기능
- 선언
- public static OpenPopupDirectMessage($sendMessage: string, $userIds?: string\[], $onComplete?: System.Action$1)\:void;
- 매개변수
| **매개변수** | **설명** |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sendMessage | 이 매개변수는 필수입니다. 이것은 보내고자 하는 메시지의 본문입니다. 비어 있거나 공백인 경우 전송은 실패로 처리됩니다. |
| userIds | 이 매개변수는 선택 사항입니다.
userIds를 전달하면
- 선택 UI가 해당 사용자 ID 목록으로 구성됩니다.
userIds가 전달되지 않거나 빈 목록이 전달되면
- 선택 UI가 메시지를 보내는 사용자의 팔로우/팔로잉 목록으로 구성됩니다. |
| onComplete | 이것은 메시지 전송이 완료되거나 실패했을 때 호출되는 콜백입니다. |
### 다이렉트 메시지 팝업 상태
| **응답** | **설명** |
| ------ | --------------------------- |
| 취소 | 팝업이 수동으로 닫히거나 전송이 실패할 때입니다. |
| 전송 완료 | 전송 요청이 완료되고 닫힐 때입니다. |
### 오류 코드별 상황
| **응답** | **설명** |
| ------ | -------------------------------------------------------- |
| 31002 | 사용자 ID 목록에 잘못된 UserID(존재하지 않는 UserID)가 포함된 경우 발생합니다. |
| 37011 | 게스트 계정으로 메시지를 보내려고 할 때 발생합니다. |
| 8001 | 같은 메시지를 반복해서 계속 보낼 때 발생합니다. 10초마다 한 번 보낼 수 있습니다. |
| 2001 | ‘보내기’ 필드의 메시지 내용이 비어 있거나, 공백만 포함되거나, 1000자를 초과할 때 발생합니다. |
| 0 | 네트워크 연결 오류 사례로, 네트워크 연결 끊김, 연결 불안정 및 기타 일반 오류 상황이 포함됩니다. |
| -1 | 식별할 수 없는 오류입니다. |
## 사용 예시
### 발신자를 직접 입력하고 전송
1\) 캔버스에 DM 전송 버튼을 추가해 주세요.
2\) 아래와 같이 예제 코드를 작성해 주세요.
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { SocialService, DirectMessagePopupState } from 'ZEPETO.Module.Social';
import { Button } from "UnityEngine.UI";
import { WorldService } from 'ZEPETO.World';
export default class SendDirectMessage extends ZepetoScriptBehaviour {
// 직접 메시지를 저장할 변수
public message: string;
// 직접 메시지를 보낼 사용자 ID 배열
public userIds: string[];
// 버튼 UI 컴포넌트에 대한 참조
public sendDMButton: Button;
Start() {
this.sendDMButton.onClick.AddListener(() => {
// 내 ID가 userIds 배열에 포함되어 있는지 확인하고 포함되어 있으면 반환
if (this.userIds.includes(WorldService.userId)) {
console.log("userIds에 내 userId가 포함되어 있습니다.");
return;
}
// SocialService를 사용하여 직접 메시지를 보내기 위한 팝업을 엽니다.
SocialService.OpenPopupDirectMessage(this.message, this.userIds, (popupState: DirectMessagePopupState) => {
// 직접 메시지 팝업의 상태를 확인합니다.
if (popupState === DirectMessagePopupState.Cancel) {
console.log("팝업을 닫았거나 메시지 전송에 실패했습니다.");
} else if (popupState === DirectMessagePopupState.SendComplete) {
console.log("DM 메시지가 성공적으로 전송되었고 팝업이 닫혔습니다.");
}
});
});
}
}
```
3\) 스크립트를 작성한 후 Unity 에디터로 돌아가서 인스펙터에서 버튼을 드래그하여 설정합니다. 메시지 본문과 대상 사용자의 UserID를 입력합니다.
- 최대 20명이 UI에 표시되므로 최대 20명을 입력하세요.
4\) DM 전송 버튼을 누르면 친구 목록 UI가 나타납니다.
- 대상 사용자를 선택하고 전송을 클릭하세요.
5\) DM 전송이 성공하면 성공을 나타내는 Toast UI가 나타나고, 예제 스크립트에 의해 로그가 출력됩니다.
6\) 또한, targetUser에게 DM이 도착했습니다.
- 연속으로 메시지를 전송하거나 메시지 내용이 비어 있는 경우와 같은 오류가 발생하면 DM 전송은 실패로 처리됩니다.
### 다음/팔로워 목록 UI를 사용하여 전송
1\) 캔버스에 버튼을 추가해 주세요.
2\) 아래와 같이 예제 코드를 작성해 주세요.
- 빈 목록을 targetUserID 매개변수에 전달하면 다음/팔로워 목록 UI가 나타납니다.
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { SocialService, DirectMessagePopupState } from 'ZEPETO.Module.Social';
import { Button } from "UnityEngine.UI";
export default class SendDirectMessage extends ZepetoScriptBehaviour {
// 직접 메시지를 저장할 변수
public message: string;
// 버튼 UI 구성 요소에 대한 참조
public sendDMButton: Button;
// null로 초기화된 사용자 ID 배열을 저장할 개인 변수
private emptyIds: string[];
Start() {
this.sendDMButton.onClick.AddListener(() => {
// SocialService를 사용하여 직접 메시지를 보내기 위한 팝업을 엽니다.
// 클래스의 메시지 내용과 빈 사용자 ID 배열을 사용합니다.
SocialService.OpenPopupDirectMessage(this.message, this.emptyIds, (popupState: DirectMessagePopupState) => {
// 직접 메시지 팝업의 반환 상태를 확인합니다.
if (popupState === DirectMessagePopupState.Cancel) {
console.log("팝업을 닫거나 메시지 전송에 실패했습니다.");
} else if (popupState === DirectMessagePopupState.SendComplete) {
console.log("DM 메시지가 성공적으로 전송되었고 팝업이 닫혔습니다.");
}
});
});
}
}
```
3\) 스크립트를 작성한 후, Unity 편집기로 돌아가서 인스펙터에서 버튼을 드래그하여 설정합니다. 그런 다음 메시지 본문을 입력해 주세요.
4\) DM 보내기 버튼을 누르면 Following/Follower UI가 나타납니다.
- 대상 사용자를 선택하고 보내기를 클릭합니다. (최대 5명까지 선택할 수 있습니다)
:::hint{type="danger"}
- 한 번에 최대 5명에게 DM을 보낼 수 있습니다.
- 자신에게 DM을 보낼 수 없습니다.
- 실제 팔로잉/팔로워 사용자 수는 DM 보내기 팝업에 표시된 사용자 수와 다를 수 있습니다.
- 선택할 수 있는 사용자들이 필터링되어 표시되기 때문입니다.
- DM 수신을 차단한 사용자를 선택하면 실패로 처리되며 DM이 전송되지 않습니다.
- Send DM API를 자주 호출하면 제한이 걸리고 전송이 실패합니다.
- 10초마다 한 번 보낼 수 있습니다. 무차별 DM을 보내지 않도록 주의해 주세요.
- 보내는 메시지에 URL이 포함되어 있으면 제대로 작동하지 않으므로 URL이 포함된 메시지 전송은 금지됩니다.
- 전송되는 메시지가 비어 있거나 공백일 경우 실패로 처리됩니다. 메시지 내용을 반드시 작성해 주세요.
:::