Dooray! > Messenger > 슬래시 커맨드 가이드
연동 서비스
Dooray! 메신저에서는 사람이 아닌 다양한 도구에게 명령하고 메시지를 받으면서 더 효율적으로 업무를 할 수 있습니다. 메신저에서 제공하지 않는 기능을 직접 구현하고 싶을 때 이 기능을 활용하여 여러분도 자신의 업무를 좀 더 효율적으로 자동화 할 수 있습니다. 소개할 기능은 커맨드를 직접 생성하는 것에 대한 내용이며, 앞으로 봇, API 등 다양한 연동 서비스를 제공할 예정입니다.
슬래시 커맨드
슬래시 커맨드(이하 커맨드)는 /문자 뒤에 덧붙여서 특정한 기능을 수행하도록 하는 명령어입니다. Dooray! 메신저에서는 기본적으로 /mute, /status, /search 등의 커맨드를 제공합니다.예컨대 메시지 내용을 찾거나, 자신의 상태를 바꾸는 등의 기능을 마우스의 클릭이나 다른 조작 없이 키보드 입력만으로 빠르게 실행할 수 있도록 도와줍니다.
자신이 원하는 기능을 수행하는 커맨드를 직접 만들어 사용할 수 있습니다. 예를 들어 매일 아침 교통 정보와 날씨를 메시지로 받아볼 수 있고, 간단한 명령어를 입력하여 투표를 생성할 수도 있습니다.
아래 그림은 커맨드 서버와 메신저 서버 간의 통신 과정입니다.
사용자는 /문자와 대화방에 등록된 커맨드를 입력합니다. 입력한 커맨드 정보는 메신저 서버를 통해 커맨드 서버로 전송이 됩니다. 커맨드 서버에서 처리한 결과를 메신저 서버로 전송합니다. 메신저 서버는 커맨드 서버로부터 받은 데이터를 기반으로 사용자에게 결과를 보여줍니다.
사용 환경
사용자는 PC와 모바일에서 커맨드를 입력하고 결과를 확인할 수 있습니다. 그렇기 때문에 커맨드 제작자는 모바일 환경에서의 레이아웃도 신경써야 합니다. 현재 대화방에 커맨드를 추가하는 기능은 PC에서만 제공합니다.
제작 가이드
커맨드의 제작 및 등록 방법에 대해서는 아래의 문서에서 설명합니다.
커맨드 추가하기
직접 만든 커맨드를 사용하기 위해서 Dooray! 메신저에 추가해야 합니다.
추가 화면으로 이동
Dooray! 메신저 좌측 상단의 자신의 이름을 선택 '연동 서비스' 메뉴를 선택합니다.
아래와 같이 빈 화면이 표시됩니다.
앱 추가
우선 앱을 만들어야 합니다. 앱은 연동 서비스의 묶음 단위입니다. 하나의 앱에 여러 개의 커맨드를 추가할 수 있습니다. 아래의 정보를 입력하여 앱을 만들어 봅니다.각 정보는 대화방에 공개된 커맨드를 등록할 때 목록에 노출됩니다.
| 구분 | 설명 |
|---|---|
| Image | 대화방에서 커맨드를 사용할 때 메시지의 전송자 아이콘으로 표시됩니다. |
| Name | 대화방에서 커맨드를 사용할 때 메시지의 전송자 이름으로 표시됩니다. |
| Description | 앱의 설명입니다. |
이제 앱이 만들어졌습니다. 생성되어 있는 토큰과 비어 있는 커맨드 목록을 보실 수 있습니다. 토큰은 커맨드 요청시 함께 전송되어 요청을 검증하는데에 사용합니다. 토큰이 외부에 유출되지 않도록 주의하시기 바랍니다. 만약 토큰이 외부에 유출된 경우에는 'Regenerate' 버튼을 이용해 기존 토큰을 파기하고 다시 발급해 사용하세요.
커맨드 추가
앱을 등록한 후, 슬래시 커맨드 영역의 '추가' 버튼을 누르면 커맨드를 추가할 수 있습니다. 되도록 하나의 앱에는 서로 밀접하게 관계가 있는 커맨드를 추가하는 것을 권장합니다.미리 제작한 커맨드가 없다면, 아래의 예제대로 /hi 커맨드를 추가해 보세요.
| 구분 | 설명 |
|---|---|
| Command | /를 포함하여 대화방에서 입력할 명령어를 입력합니다.명령어는 커맨드의 기능을 나타내는 직관적인 것이 좋습니다. |
| Request URL | 커맨드를 실행 시 요청할 커맨드 서버 URL을 입력합니다. |
| Description | 커맨드 사용할 때 표시될 설명입니다. 다른 사람이 커맨드의 기능을 쉽게 이해할 수 있도록 적어주세요. |
| Parameter Hint | 커맨드와 함께 어떤 파라미터를 적어야 하는지 설명해 주세요. (지역, 시간, 사람, 날짜, 텍스트, 숫자 등의 정보를 입력할 수 있습니다.) |
| Public | 해당 커맨드를 다른 사람들도 대화방에 추가하여 사용할 수 있습니다. |
커맨드가 추가되었습니다.
Interactive Request URL 입력
버튼과 드롭다운 메뉴를 통해 사용자의 액션을 받으려면 Interactive Message 처리를 위한 별도의 URL이 필요합니다.
| 구분 | 설명 |
|---|---|
| Interactive Message Request URL | 버튼과 드롭다운 메뉴 등 메시지를 통해서 유저와 상호 작용하는 경우, 유저의 요청을 전달할 URL을 입력합니다. |
| Interactive Message Optional URL | 메시지에 dataSource를 external로 설정한 메뉴 목록 등을 제공하는 경우, 메뉴 목록을 요청할 URL을 입력합니다. |
"Hello World!" 메시지 보내기
대화방에서 /hi라고 입력하면, "Hello world!"라고 대답하는 아주 간단한 커맨드를 만들어 보겠습니다.
커맨드 실행
사용자가 Dooray! 메신저를 통해 /hi 커맨드를 실행하면 커맨드 서버는 아래와 같은 JSON 데이터를 전달받습니다.
POST [Request URL]
{
"tenantId": "1234567891234567891",
"tenantDomain": "guide.dooray.com",
"channelId": "1234567891234567891",
"channelName": "커맨드 가이드 채널",
"userId": "1234567891234567891",
"command": "/hi",
"text": ""
"responseUrl": "https://guide.dooray.com/messenger/api/commands/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"appToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"cmdToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"triggerId": "1234567891234.xxxxxxxxxxxxxxxxxxxx"
}
| 필드명 | 설명 |
|---|---|
| tenantId | 커맨드가 등록된 테넌트의 ID |
| tenantDomain | 커맨드가 등록된 테넌트의 도메인 |
| channelId | 커맨드가 요청한 대화방의 ID |
| channelName | 커맨드를 요청한 대화방의 이름 |
| userId | 커맨드를 요청한 사용자 ID |
| command | 요청한 커맨드 |
| text | 커맨드와 함께 입력한 텍스트 |
| responseUrl | 커맨드 요청에 응답할 수 있는 웹 훅 URL |
| appToken | 등록한 앱의 토큰. 정상 요청인지 검증할 때 사용 |
| cmdToken | API 호출 시에 사용하는 Token |
| triggerId | 다이얼로그에 사용하는 값 |
응답
커맨드 서버는 전달받은 데이터를 이용해 사용자에게 응답할 데이터를 만듭니다. 그리고 이 데이터를 요청에 대한 응답으로 보내야 합니다. /hi 커맨드는 특별한 데이터 처리 없이 Hello World!만 보내주면 됩니다.
{
"text": "Hello World!",
"responseType": "ephemeral"
}
위와 같이 응답하면 커맨드를 호출한 사용자에게만 보이는 메시지가 됩니다. 만약 대화방 내의 멤버들에게 모두 보여주고 싶은 경우 responseType을 inChannel로 응답에 추가하면 됩니다.
{
"text": "Hello World!",
"responseType": "inChannel"
}
| 필드명 | 기본값 | 설명 |
|---|---|---|
| responseType | ephemeral | 메시지 게시 타입을 설정합니다. - inChannel: 전체 사용자에게 표시 - ephemeral: 호출한 사용자에게만 표시 |
| text | 메시지 내용 |
메시지를 전송하는 네 가지 방법
커맨드 실행 시, 메신저 서버는 네 가지의 방식으로 메시지를 전송할 수 있습니다.
- 최초로 메시지를 전송
- 메시지를 보낸 후 추가로 전송
- 기존에 보낸 메시지를 업데이트
- 기존에 보낸 메시지를 삭제하고 메시지를 새로 전송
위 4가지 방식으로 메시지를 전송하고 싶으면, 아래의 페이로드와 같이 커맨드 실행 요청에 대한 응답을 해주면 됩니다.
메시지를 최초 전송
메시지를 새로 보내는 방법은 간단합니다.
{
"responseType": "inChannel",
"text": "Hello World!"
}
메시지를 추가로 전송
replaceOriginal을 false로 하면 메시지를 새로 전송합니다.
{
"replaceOriginal": false,
"responseType": "inChannel",
"text": "Hello World!"
}
기존에 보낸 메시지를 업데이트
replaceOriginal을 true로 하면 기존에 보낸 메시지의 위치에 그대로 내용만 변경되며, 알림도 오지 않습니다. 기존 메시지의 responseType을 바꾸어 업데이트할 수 없습니다. responseType을 바꾸기 위해선 메시지를 새로 전송해야 합니다.
{
"responseType": "inChannel",
"replaceOriginal": true,
"text": "Hello World!(Updated)"
}
기존에 보낸 메시지를 삭제하고 메시지를 새로 전송
이 경우에는 대화방의 참여자에게 알림이 가기 때문에 대화방의 사람들이 변경되는 내용을 알게 하고 싶을 때 효과적입니다. deleteOriginal을 true로 하면 기존 메시지가 삭제되고 다시 전송됩니다.
{
"responseType": "inChannel",
"deleteOriginal": true,
"text": "Hello World!(Updated)"
}
필요한 기능에 맞는 메시지 전송 방법을 선택하여 커맨드를 제작하시기 바랍니다.
메시지에 버튼 넣기
응답 메시지는 attachments 필드를 이용해 버튼을 표시할 수 있습니다. 메시지를 받은 사람은 버튼을 눌러 상호작용을 할 수 있습니다. 버튼을 넣는 방법과 버튼을 선택한 결과를 받아 처리하는 방법을 알아보겠습니다.
아래는 입력한 메시지를 대화방에 전송할지 확인하는 attachments가 포함된 메시지입니다.
{
"text": "Message",
"attachments": [
{
"callbackId": "send-a1b2c3", // 사용자 상호 작용 시 함께 전송됩니다. 상호 작용이 일어난 attachment를 식별할 때 쓸 수 있습니다.
"actions": [
{
"name": "send",
"type": "button",
"text": "Send", // 사용자에게 출력되는 버튼 텍스트
"value": "posting", // Action 동작에 사용하는 (사용자에게 보이지 않는) 값
"style": "primary" // 버튼의 스타일을 바꿀 수 있습니다. primary, danger, default
},
{
"name": "send",
"type": "button",
"text": "Cancel",
"value": "cancel"
}
]
}
]
}
해당 메시지를 받으면, 아래와 같이 'Send'와 'Cancel' 버튼이 있는 메시지가 생성된 것을 확인할 수 있습니다.
'Send' 버튼을 눌러봅시다. 아래와 같은 데이터가 커맨드 서버의 Interactive Request URL로 전송됩니다.
{
// 테넌트, 채널, 멤버 정보가 제공됩니다.
"tenant": {
"id": "1234567891234567891",
"domain": "guide.dooray.com"
},
"channel": {
"id": "1234567891234567891",
"name" "커맨드 가이드 채널"
},
"user": {
"id": "1234567891234567891",
},
"commandName": "/post",
"command": "/post",
"text": "",
"callbackId": "send-a1b2c3", // 사용자가 선택한 Action이 속해있는 Attachment의 callbackId입니다.
"actionName": "Send", // actionName - 사용자가 선택한 Action의 Name입니다.
"actionValue": "posting", // actionValue - 사용자가 선택한 Action의 Value입니다.
"appToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"cmdToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"triggerId": "",
"commandRequestUrl": "https://command.example.com/req",
"channelLogId": "-7386965175150134411",
"originalMessage": { /* action이 발생한 메시지가 포함됩니다. */ }
}
}
사용자가 버튼을 눌렀을 때의 처리는 커맨드 서버에서 구현해야 합니다.
메시지에 드롭다운 메뉴 넣기
attachments 메시지 안에는 드롭다운 메뉴를 넣을 수 있습니다. 드롭다운 메뉴로 채널 목록, 테넌트의 멤버 목록, 또는 임의의 목록에서 하나를 선택할 수 있습니다.
아래 예시에서는 팀원들이 가장 좋아하는 보드 게임을 뽑아서 함께 플레이하려고 합니다. 아래의 메시지처럼 보드 게임 목록이 있는 드롭다운 메뉴를 활용하여 투표를 받아봅시다.
정적 드롭다운 메뉴
options 필드를 이용해 목록을 구성할 수 있습니다.
"attachments": [
{
"name": "games_list",
"text": "Pick a game...",
"type": "select",
"options": [
{
"text": "rock-scissors-paper",
"value": "rcp"
},
{
"text": "monopoly",
"value": "monopoly"
},
{
"text": "Checkers",
"value": "checkers"
},
{
"text": "Chess",
"value": "chess"
},
{
"text": "Poker",
"value": "poker"
},
{
"text": "scrabble",
"value": "scrabble"
}
]
}
]
위 attachments를 통해 아래 화면과 같은 드롭다운 메뉴를 보여줄 수 있습니다.
동적 드롭다운 메뉴
동적 드롭다운 메뉴는 options 대신 dataSource를 이용합니다. dataSource는 값에 따라 멤버, 대화방, 외부 데이터를 보여줄 수 있습니다.
| dataSource | 목록 |
|---|---|
| users | 멤버 |
| channels | 대화방 |
| external | 외부 데이터 |
멤버 목록
dataSource에 users로 메시지를 구성해 전송하면 현재 대화방의 멤버 목록을 보여줄 수 있습니다. 사용자가 드롭다운 메뉴에 검색어를 입력해 테넌트 전체 멤버를 검색 할 수 있습니다.
"attachments": [
{
"actions": [
{
"type": "select",
"name": "sel_users",
"text": "사용자 출력",
"dataSource": "users"
}
]
}
]
대화방 목록
dataSource에 channels로 메시지를 구성해 전송하면 사용자가 속한 대화방 목록을 보여줄 수 있습니다.
"attachments": [
{
"actions" : [
{
"type": "select",
"name": "sel_channels",
"text": "대화방 출력",
"dataSource": "channels"
}
]
}
]
외부 데이터 목록
dataSource에 external로 메시지를 구성해 전송하면 외부 데이터 목록을 보여줄 수 있습니다. 외부 데이터 목록은 앱 설정시 등록한 Interactive Optional URL로 데이터를 요청해 받아옵니다.
"attachments": [
{
"actions": [
{
"type": "select",
"name": "sel_external",
"text": "외부 데이터",
"dataSource": "external"
}
]
}
]
클라이언트는 Interactive Optional URL로 아래 메시지와 함께 외부 데이터 목록을 요청합니다.
{
"type": "interactive_message",
"tenant": {
"id": "1234567891234567891",
"domain": "guide.dooray.com"
},
"channel": {
"id": "1234567891234567891",
"name": "Command 가이드 채널"
},
"user": {
"id": "1234567891234567891",
"name": "홍길동"
},
"callbackId": "sample",
"actionName": "sel_externel",
"actionTs": 1524734546105
}
커맨드 서버에서 위 메시지를 이용해 드롭다운 메뉴의 목록을 응답해 줍니다.
{
"options": [
{
"text": "external",
"value": "value1"
},
{
"text": "load",
"value": "value2"
},
{
"text": "success",
"value": "value3"
}
]
}
attachments 메시지 보내기
커맨드는 attachments라는 특별한 형태의 메시지를 전송할 수 있습니다. attachments의 구성 요소에는 다른 문서에서 설명하였던 버튼과 드롭다운 메뉴 외에도 다양한 것이 있습니다. attachments 메시지를 잘 사용하면 사용자의 눈에 잘 띌뿐 아니라 추가 정보를 요청하거나 회신하는 등의 행동을 능숙하게 유도할 수 있습니다.
attachments 메시지
아래의 보시는 메시지의 블록 하나 하나가 타이틀, 설명, 이미지, 링크, 버튼, 드롭다운 메뉴 등을 가질 수 있는 attachment입니다. 최대 20개의 attachment 블록이 모여 attachments 메시지를 구성합니다.
| 번호 | 이름 | 설명 |
|---|---|---|
| 1 | text | 메시지의 내용입니다. |
| 2 | attachment | 메시지에 첨부한 내용입니다. 여러 개의 attachment를 합쳐서 attachments라고 부릅니다. |
| 3 | authorName | 작성자 이름입니다. authorLink로 링크를 걸 수 있습니다. |
| 4 | title | attachment의 제목입니다. |
| 5 | text | attachment의 내용입니다. |
| 6 | thumbUrl | attachment에 넣을 섬네일 이미지입니다. |
| 7 | imageUrl | attachment에 넣을 이미지 URL입니다. |
| 8 | field | short의 값에 따라 한 줄에 하나 또는 두 개씩 표시되는 필드입니다. |
| 10 | Interactive Menu | 드롭다운 메뉴입니다. |
| 11 | Interactive Button | 버튼입니다. |
데이터
데이터의 포맷은 아래와 같습니다.
{
"text": "NHN IT News!",
"attachments": [
{
"callbackId": "guide-a1b2c3",
"text": "애플은 오늘 오전 2시에 WWDC를 통해 아이폰X 출시를 알렸다.",
"title": "아이폰 X 출시",
"titleLink": "https://dooray.com/",
"authorName": "NHN News",
"authorLink": "https://dooray.com/",
"imageUrl": "http://it.chosun.com/data/photos/cdn/20180423/2850453_09555838720000.jpg",
"thumbUrl": "http://www.kinews.net/news/photo/201804/119143_167793_5622.png",
},
{
"fields": [
{
"title": "출시 예정일",
"value": "2018년 겨울",
"short": true
},
{
"title": "예상 가격",
"value": "125만원",
"short": true
}
]
},
{
"fields": [
{
"title": "설명",
"value": "한국 미출시",
}
]
},
{
"fields": [
{
"title": "IOS",
"value": "High Sierra OS",
}
]
},
{
"actions": [
{
"type": "select",
"text": "채널선택",
"name": "guide-sel",
"dataSource": "channels"
}
]
},
{
"actions": [
{
"type": "button",
"text": "공유하기",
"name": "guide-btn",
"value": "btnValue"
},
{
"type": "button",
"text": "다음 뉴스",
"name": "guide-btn",
"value": "btnValue"
},
]
}
]
}
구성 요소 분석
데이터의 구성 요소를 좀 더 자세히 살펴 보겠습니다.
Message Object
| 필드명 | 기본값 | 설명 |
|---|---|---|
| text | 메시지 텍스트 | |
| attachments | Attachment의 배열 | |
| responseType | "ephemeral" | 메시지 표시 대상 - "ephemeral": Command를 실행한 사용자에게만 표시 - "inChannel": 채널 내 전체 사용자에게 표시 |
| replaceOriginal | true | Interactive Message에 대한 응답 시 기존 메시지 수정 여부 |
| deleteOriginal | false | Interactive Message에 대한 응답 시 기존 메시지 삭제 여부 |
Attachment Object
| 필드명 | 기본값 | 설명 |
|---|---|---|
| text | Attachment 텍스트 | |
| title | Attachment 제목 | |
| titleLink | Attachment 제목 클릭 시 이동할 링크 | |
| authorName | Attachment 작성자 | |
| authorLink | Attachment 작성자 클릭 시 이동할 링크 | |
| fields | Field의 배열 | |
| actions | Action의 배열 | |
| callbackId | Action 요소 작동 시 함께 전달될 값(세션 유지 등의 용도로 사용) | |
| imageUrl | 이미지 주소 | |
| thumbUrl | 섬네일 주소 | |
| color | #4757C4 | Attachment 세로줄 색상(HTML 색상코드) |
Field Object
| 필드명 | 기본값 | 설명 |
|---|---|---|
| title | Field 제목 | |
| value | Field 텍스트 | |
| short | false | Field 너비 설정(true로 설정 시 절반 너비) |
Action Object
| 필드명 | 기본값 | 설명 |
|---|---|---|
| type | Actiontype - "button": 버튼 - "select": 드롭다운 메뉴 |
|
| text | 버튼, 드롭다운 메뉴에 표시될 텍스트 | |
| name | 커맨드 서버에 전달되는 필드명 | |
| value | 커맨드 서버에 전달되는 필드값 | |
| style | "default" | 버튼 색상 - "primary": 강조 색상 - "default": 기본 색상 |
| options | Option의 배열 | |
| dataSource | 'options' 대신 지정할 수 있는 option 값 - "users": 사용자 목록 - "channels": 채널 목록 - "external": Interactive Message Optional URL에서 가져오기 |
Option Object
| 필드명 | 기본값 | 설명 |
|---|---|---|
| text | Option 텍스트 | |
| value | 커맨드 서버에 전달되는 필드값 |
Incoming Webhook(responseUrl)
슬래시 커맨드의 특성에 따라 임의의 시간에 메시지를 보내야 하는 경우가 있습니다.(예시: 매일 특정 시간에 오늘의 일정을 알려주는 슬래시 커맨드) 이 경우에는 responseUrl을 활용해 메시지를 전송합니다.
요청 방법
POST https://{tenantDomain}/messenger/api/commands/hook/{cmdToken}
request body
attachments 메시지 보내기의 Message Object를 참조
{
"responseType": "ephemeral",
"text": "Click 'Submit' button to start the vote.",
"attachments": [
{
"title": "점심식사",
"fields": [
{
"title": "Item 1",
"value": "짜장면",
"short": true
},
{
"title": "Item 2",
"value": "짬뽕",
"short": true
},
{
"title": "Item 3",
"value": "탕수육",
"short": true
}
]
},
{
"callbackId": "vote",
"actions": [
{
"name": "vote",
"type": "button",
"text": "Submit",
"value": "\"점심식사\" \"짜장면\" \"짬뽕\" \"탕수육\"",
"style": "primary"
},
{
"name": "vote",
"type": "button",
"text": "Cancel",
"value": "cancel"
}
]
}
]
}
결과 반환
- 성공 여부: $.header.isSuccessful에 true, false 값을 반환합니다.
- 실패 원인: $.header.resultCode에 코드 값을 $.header.resultMessage에 상세 실패 정보를 반환합니다.
대화 상자 사용하기
별도의 영역에서 정보를 입력받을 수 있는 대화 상자를 띄웁니다.
요청 방법
POST https://{tenantDomain}/messenger/api/channels/{channelId}/dialogs
request header
- token: cmdToken
request body
{
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
triggerId: "1111111111111.xxxxxxxxxxxxxxxxxxxx.3333333333333",
callbackId: "guide-a1b2c3",
dialog: {
callbackId: 'guide-a1b2c3',
title: 'Guide Dialog',
submitLabel: 'Send',
elements: [
{
type: 'text',
subtype: 'number',
label: 'Page Number',
name: 'page',
value: 0,
minLength: 1,
maxLength: 2,
placeholder: '0 ~ 50',
hint: 'Must in 0 ~ 50'
},
{
type: 'textarea',
label: 'Note',
name: 'note',
optional: true
},
{
type: 'select',
label: 'Is this important?',
name: 'important',
value: 'false',
options: [
{
label: 'Yes',
value: 'true'
},
{
label: 'No',
value: 'false'
}
]
}
]
}
}
| 필드명 | 기본값 | 설명 |
|---|---|---|
| triggerId | 어떤 커맨드 요청에서 유발된 Dialog인지 구분해주는 값 | |
| callbackId | 전송할 때 함께 전달될 값(세션 유지 등의 용도로 사용) | |
| title | Dialog 제목 | |
| submitLabel | "Submit" | 전송 버튼 텍스트 지정 |
| elements | Element의 배열 |
결과 반환
- 성공 여부: $.header.isSuccessful에 true, false 값을 반환합니다.
- 실패 원인: $.header.resultCode에 코드 값을 $.header.resultMessage에 상세 실패 정보를 반환합니다.
Element Object
| 필드명 | 기본값 | 설명 |
|---|---|---|
| type | 필드 타입 "text": 텍스트 필드 "textarea": 장문 텍스트 필드 "select": 드롭 메뉴 |
|
| subtype | type이 text일 때 모바일에서 출력할 키보드 타입 "number", "email", "tel", "url" |
|
| label | 사용자에게 출력되는 필드명 | |
| name | 커맨드 서버에 전달되는 필드명 | |
| value | 필드에 기본으로 입력된 값(type이 select일 때 Option value로 지정해두면 자동 선택) | |
| options | type이 select일 때 출력되는 Option의 배열 | |
| dataSource | type이 select일 때 options 대신 출력할 데이터 | |
| minLength | 최소 입력 글자수 | |
| maxLength | 최대 입력 글자수 | |
| placeholder | 필드에 출력되는 힌트(입력 시 사라짐) | |
| hint | 필드 아래에 출력되는 힌트 | |
| optional | false | 해당 필드의 필수 입력 여부 설정(false로 하면 필수 입력) |
Option Object
| 필드명 | 기본값 | 설명 |
|---|---|---|
| label | Option 텍스트 | |
| value | 커맨드 서버에 전달되는 필드값 |
대화 상자 전송 처리
위의 API를 활용해 사용자에게 대화 상자를 띄웠습니다. 이후 사용자가 해당 대화 상자를 작성해서 전송하면 이를 처리해야 합니다.
메신저 서버에서 커맨드 서버로의 요청
{
"type": "dialog_submission",
"tenant": {
"id": "1234567891234567891",
"domain": "guide.dooray.com"
},
"channel": {
"id": "1234567891234567891",
"name": "커맨드 가이드 채널"
},
"user": {
"id": "1234567891234567891"
},
"responseUrl": "https://guide.dooray.com/messenger/api/commands/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"cmdToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"updateCmdToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"prevCmdToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"callbackId": "guide-a1b2c3",
"submission": {
"page": "100",
"note": "자주 봐야하는 부분",
"important": "true"
}
}
| 필드명 | 설명 |
|---|---|
| type | 발생한 이벤트의 타입(dialog_submission) |
| tenant | 커맨드를 호출한 사용자가 속한 테넌트의 정보 |
| channel | 커맨드를 호출한 채널의 정보 |
| user | 커맨드를 호출한 사용자의 정보 |
| responseUrl | 커맨드를 호출에 응답하기 위한 인커밍 웹훅 URL |
| cmdToken | API 호출 시에 사용하는 Token |
| callbackId | Dialog에 지정된 Callback ID |
| submission | Dialog에 지정된 element의 name과 사용자가 작성한 값을 Key와 Value로 한 Object |
커맨드 서버에서 메신저 서버로의 응답
두 가지 경우가 존재합니다.
-
사용자 입력값에 오류가 없을 경우, 응답을 비우고 HTTP 200 응답을 합니다.
-
오류가 있을 경우, HTTP 200 응답과 함께 errors로 응답합니다.
{
errors: [
{
name: 'page',
error: 'Page number는 50을 넘을 수 없습니다.'
}
]
}
| 필드명 | 기본값 | 설명 |
|---|---|---|
| name | 오류를 찾은 element의 name | |
| error | 출력할 오류 메시지 |
대화방에 커맨드 등록하기
대화방에 커맨드를 등록
커맨드는 자신이 참여하고 있는 1:1 대화, 그룹 대화 등에 등록하여 활용할 수 있습니다. 커맨드 추가 화면을 여는 방법은 두 가지가 있습니다.
첫째, 메신저 우측 상단의 설정 메뉴를 통해 추가할 수 있습니다.
둘째, 대화방의 입력창에 /를 입력 후 나타나는 화면에서 '연동 서비스' 버튼을 통해 추가할 수 있습니다.
커맨드 추가 화면에는 공개된 커맨드나 자신이 생성한 커맨드가 표시됩니다. 원하는 커맨드 우측의 '추가' 버튼을 눌러 대화방에 커맨드를 추가하세요. 만약 커맨드가 없다면 본 문서의 처음으로 돌아가 커맨드를 만들어 보세요.
커맨드 공개
만약 자신이 만든 커맨드의 멋진 기능을 조직 내의 다른 사람들과 공유하고 싶다면 공개로 설정해 주세요. 조직 내의 다른 사람들도 자유롭게 대화방에 추가하여 사용할 수 있습니다. 비공개로 변경해도 이미 추가한 커맨드는 다른 사람이 계속 사용할 수 있으니, 다른 사람들이 더 이상 커맨드를 사용하지 못하게 하려면 등록한 커맨드를 삭제해 주세요.
예제: 투표 커맨드
커맨드 서버 요구사항
커맨드 서버는 등록한 커맨드대로 동작하는 REST API를 제공해야 합니다.
| API 종류 | 설명 | 필수 | 메소드 |
|---|---|---|---|
| 커맨드 Request URL | 사용자의 커맨드 실행 요청을 처리할 URL | O | POST |
| Interactive Message의 Request URL | 사용자의 액션(버튼 클릭, 드롭다운 메뉴 선택)을 처리할 URL | X | POST |
| Interactive Message의Optional URL | 드롭다운 메뉴에서 외부 데이터 제공할 URL | X | POST |
투표 커맨드
예제로 대화방에 투표를 만들고 참여할 수 있는 투표 커맨드를 만들겠습니다. 예제 코드는 Github에서 확인할 수 있습니다.
API
커맨드 Request URL과 Interactive Message의 Request URL만 사용합니다.
커맨드 실행 포맷
사용자가 투표 커맨드를 실행할 입력 포맷은 아래처럼 입력하도록 합니다.
/vote {제목} {항목1} "{공백을 포함한 항목}" ... {항목n}
시나리오
- 사용자가 커맨드 실행
- 커맨드를 실행한 사용자에게만 보이는 투표 생성 확인 메시지 출력
- 생성 버튼을 눌러서 대화방 멤버에게 모두 보이는 투표 메시지 출력
- 대화방 멤버들이 투표 버튼으로 투표 참여
- 투표를 생성한 사용자가 투표 종료
- 투표 결과 출력
투표 커맨드 실행 요청
사용자가 투표 커맨드를 아래와 같이 실행합니다.
커맨드 서버는 커맨드 Request URL로 사용자가 입력한 값을 포함한 JSON 데이터를 받게 됩니다.
{
"tenantId": "1234567891234567891",
"tenantDomain": "guide.dooray.com",
"channelId": "1234567891234567891",
"channelName": "Command 가이드",
"userId": "1234567891234567891",
"command": "/vote",
"text": "점심식사 짜장면 짬뽕 \"사천 탕수육\"",
"responseUrl": "https://guide.dooray.com/messenger/api/commands/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"appToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"cmdToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"triggerId": "1234567891234.xxxxxxxxxxxxxxxxxxxx"
}
| 필드명 | 설명 |
|---|---|
| tenantId | 커맨드가 등록된 테넌트의 ID |
| tenantDomain | 커맨드가 등록된 테넌트 도메인 |
| channelId | 커맨드를 요청한 대화방의 ID |
| channelName | 커맨드를 요청한 대화방 제목 |
| userId | 커맨드를 요청한 사용자 ID |
| command | 커맨드 이름 |
| text | 사용자가 입력한 전체 텍스트 |
| responseUrl | 커맨드를 요청한 대화방의 Webhook URL |
| appToken | 커맨드를 등록한 앱의 토큰(요청 검증으로 활용) |
| cmdToken | API 호출 시에 사용하는 Token |
| triggerId | 다이얼로그 실행 ID |
커맨드 실행 요청에 대한 응답
커맨드 실행 요청에 대한 응답으로 실행 사용자에게만 보이는 확인 메시지를 보냅니다. 투표를 생성하거나 취소할 수 있는 버튼을 사용자에게 제공하기 위해 아래와 같이 메시지를 전송합니다.
{
"responseType": "ephemeral",
"text": "Click 'Submit' button to start the vote.",
"attachments": [
{
"title": "점심식사",
"fields": [
{
"title": "Item 1",
"value": "짜장면",
"short": true
},
{
"title": "Item 2",
"value": "짬뽕",
"short": true
},
{
"title": "Item 3",
"value": "사천 탕수육",
"short": true
}
]
},
{
"callbackId": "vote",
"actions": [
{
"name": "vote",
"type": "button",
"text": "Submit",
"value": "점심식사 짜장면 짬뽕 \"사천 탕수육\"",
"style": "primary"
},
{
"name": "vote",
"type": "button",
"text": "Cancel",
"value": "cancel"
}
]
}
]
}
액션 실행 요청
사용자가 전송 버튼을 누르면 아래와 같은 데이터가 Interactive Message의 Request URL로 전송됩니다.
{
"tenant": {
"id": "1234567891234567891",
"domain": "guide.dooray.com"
},
"channel": {
"id": "1234567891234567891",
"name": "Command 가이드 채널"
},
"user": {
"id": "1234567891234567891",
"name": "홍길동"
},
"commandName": "/vote",
"command": "/vote",
"text": "점심식사 짜장면 짬뽕 \"사천 탕수육\"",
"callbackId": "vote",
"actionText": "Submit",
"actionValue": "점심식사 짜장면 짬뽕 \"사천 탕수육\"",
"appToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"cmdToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"triggerId": "1234567891234.xxxxxxxxxxxxxxxxxxxx",
"commandRequestUrl": "https://command.guide.doc/req",
"channelLogId": "-7386965175150134411",
"originalMessage": { /* Message Object */ }
}
| 필드명 | 설명 |
|---|---|
| callbackId | 사용자가 선택한 액션이 속해있는 Attachment의 ID |
| actionText | 사용자가 선택한 액션 텍스트 |
| actionValue | 사용자가 선택한 액션 값 |
| commandRequestUrl | 커맨드 Request URL |
| channelLogId | 메시지 ID |
| originalMessage | 이전 응답으로 받은 메시지 |
액션 실행에 대한 응답
'Submit' 버튼에 대한 응답으로 투표 생성 메시지를 전송합니다. 생성 확인 메시지는 더 이상 필요가 없기 때문에 삭제하고 메시지를 새로 생성합니다.
{
"responseType": "inChannel",
"deleteOriginal": true,
"text": "(dooray://1234567891234567891/members/1234567891234567891 \"member\") created the vote!",
"attachments": [
{
"callbackId": "1525223162093-(dooray://1234567891234567891/members/1234567891234567891 \"member\")",
"title": "점심식사",
"actions": [
{
"name": "vote",
"type": "button",
"text": "짜장면",
"value": 0
},
{
"name": "vote",
"type": "button",
"text": "짬뽕",
"value": 1
},
{
"name": "vote",
"type": "button",
"text": "사천 탕수육",
"value": 2
}
],
"color": "#4286f4"
},
{
"callbackId": "1525223162093-(dooray://1234567891234567891/members/1234567891234567891 \"member\")",
"text": "",
"actions": [
{
"name": "vote",
"type": "button",
"text": "Close the vote (Show result)",
"value": "end"
}
]
}
]
}
| 필드명 | 기본값 | 설명 |
|---|---|---|
| deleteOriginal | false | 새 메시지를 생성하기 전 기존 메시지 삭제 여부 |
| replaceOriginal | true | 기존 메시지 업데이트 여부 |
이 후 사용자가 누르는 버튼은 액션 실행 요청과 그에 따른 응답의 반복입니다.
목차
- Dooray! > Messenger > 슬래시 커맨드 가이드
- 연동 서비스
- 슬래시 커맨드
- 사용 환경
- 제작 가이드
- 커맨드 추가하기
- 추가 화면으로 이동
- 앱 추가
- 커맨드 추가
- Interactive Request URL 입력
- "Hello World!" 메시지 보내기
- 커맨드 실행
- 응답
- 메시지를 전송하는 네 가지 방법
- 메시지를 최초 전송
- 메시지를 추가로 전송
- 기존에 보낸 메시지를 업데이트
- 기존에 보낸 메시지를 삭제하고 메시지를 새로 전송
- 메시지에 버튼 넣기
- 메시지에 드롭다운 메뉴 넣기
- 정적 드롭다운 메뉴
- 동적 드롭다운 메뉴
- attachments 메시지 보내기
- attachments 메시지
- 데이터
- 구성 요소 분석
- Incoming Webhook(responseUrl)
- 요청 방법
- 결과 반환
- 대화 상자 사용하기
- 요청 방법
- 결과 반환
- 대화 상자 전송 처리
- 대화방에 커맨드 등록하기
- 대화방에 커맨드를 등록
- 커맨드 공개
- 예제: 투표 커맨드
- 커맨드 서버 요구사항
- 투표 커맨드
- 투표 커맨드 실행 요청
- 커맨드 실행 요청에 대한 응답
- 액션 실행 요청
- 액션 실행에 대한 응답