⚒️메신저 서비스알림 가이드

기본 정보

서비스 봇 등록 최대 개수

• 20개(기본 봇 제외)

• 기본 봇이란? 오피스넥스트에서 제공하는 시스템 봇

시작하기

이 문서는 오피스넥스트 메신저 서비스 알림 전송 API에 대한 전반적 이해를 돕는 것을 목적으로 합니다.

규칙

서비스알림 전송 API 요청 URL은 https://api.officewave.co.kr/api/v1/hooks/{token}/notifications 입니다.

서비스알림 전송 API를 사용하려면 토큰이 필요합니다. 토큰은 지란지교소프트 메신저 개발팀 이준태에게 연락바랍니다.

서비스알림 전송 API는 페이지와 데이터베이스 리소스에 대한 POST 요청을 통해 작업을 수행하는 RESTful 규칙을 따릅니다. 요청과 응답 본문은 JSON으로 인코딩됩니다.

JSON 규칙

• JSON 형식에 필요한 데이터는 whole, to, type, template, contents, items 입니다.

• whole 데이터는 전체 전송 여부 값이며, boolean 값입니다. true일 경우 전체 전송입니다.

• to 데이터는 받는 사람의 오피스웨이브 사용자 ID 또는 email 값을 입력하면 됩니다. 배열형식이며 여러명에게 보낼 수 있습니다. whole이 true인 경우 to 값은 빈 배열이어야 합니다.

• type 데이터는 서비스알림의 유형입니다. type 값은 default, static, carousel 값이 있습니다.

type	설명
default	버튼이나 링크가 연결되지 않고 텍스트형식만 보내는 방식입니다.
static	버튼이나 링크가 추가된 방식입니다.
carousel	static 방식의 서비스알림을 한꺼번에 묶어서 보내는 방식입니다.

• template 데이터는 서비스알림의 표현 레이아웃를 의미합니다. template 값은 text, card, list 값이 있습니다.

• template 데이터는 서비스알림의 표현 레이아웃를 의미합니다. template 값은 text, card, list 값이 있습니다.

template	설명
text	텍스트로만 구성되어있는 레이아웃입니다.
card	사진과 텍스트로 구성되어있는 레이아웃입니다.
list	사진과 텍스트로 구성된 아이템들을 여러개 표현하는 레이아웃입니다.

• contents 데이터는 서비스알림에서 type 이 default 일 때에만 사용하는 값으로써, 순수 텍스트만 보내는 경우에 사용합니다.

• items 데이터는 type이 default를 제외한 static, carousel 템플릿에서만 사용할 수 있습니다.

• 아래 타입 / 템플릿 예시의 json 값을 body에 담아서 요청하면 예시 사진과 같이 표시되게 됩니다.

사용 예시

기본 텍스트형 서비스알림

Untitled

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "whole": false,
    "to": ["[e-mail]"],
    "contents": "컨텐츠입니다.",
    "template": "text",
    "type": "default"
}

필드	속성	필수여부	설명	예시
whole	boolean	X	전체 전송 여부	false
to	array	whole이 false이거나 없는 경우 O	받는 대상 유저의 이메일 값	[”[e-mail]”, “[e-mail]”]
contents	string	O	서비스 알림의 본문 내용	“컨텐츠입니다.”
type	string	X	서비스 알림의 타입	“default”
template	string	X	서비스 알림의 레이아웃	“text”

버튼 텍스트형 서비스알림

Untitled

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["[e-mail]"],
    "template": "text",
    "type": "static",
    "important": false,
    "items":
    {
        "header": "헤더입니다.",
        "contents" : "컨텐츠입니다.",
        "buttons": [
            {
                "label": "이미지1",
                "type" : "image",
                "href": "<https://source.unsplash.com/random/300*304>"
            },
            {
                "label": "이미지2",
                "type" : "image",
                "href": "<https://source.unsplash.com/random/300*305>"
            },
            {
                "label": "이미지3"
                "type" : "image",
                "href": "<https://source.unsplash.com/random/300*306>"
            }
        ],        "button_layout" : "vertical"
    }
    
}

필드	속성	필수여부	설명	예시	비고
whole	boolean	X	전체 전송 여부	false
to	array	whole이 false이거나 없는 경우 O	받는 대상 유저의 이메일 값	[”[e-mail]”, “[e-mail]”]
type	string	X	서비스 알림의 타입	“default”
template	string	X	서비스 알림의 레이아웃	“text”
items	array	O	서비스 알림의 레이아웃 요소
items.header	string	X	text template의 header	“헤더입니다”	50자
items.contents	string	O	text template의 contents	“컨텐츠입니다”	1000자
items.buttons	array	X	text template의 버튼		버튼 최대 3개
items.buttons.label	string	O	버튼에 쓰여진 글자	“이미지 보기”	vertical: 14자 horizontal: 8자
items.buttons.type	string	O	버튼 타입	“image”	image, link, webview
items.buttons.href	string	O	버튼 클릭 했을 때 참조하는 링크 또는 코드 값	“https://source.unsplash.com/random/300*300"
items.button_layout	string	X	버튼 배치방식	“vertical”	vertical, horizontal

버튼 카드형 서비스알림

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["[e-mail]"],
    "template": "list",
    "type": "static",
    "important": false,
    "items": 
    {
        "header": "헤더입니다.",
        "items": [
            {
                "image_url": "<https://source.unsplash.com/random/301*300>",
                "title" : "이미지1",
                "contents" : "컨텐츠1",
                "type": "image",
                "href": "<https://source.unsplash.com/random/302*300>"
            },
            {
                "image_url": "<https://source.unsplash.com/random/303*300>",
                "title" : "이미지2",
                "contents" : "컨텐츠2",
                "type": "image",
                "href": "<https://source.unsplash.com/random/304*300>"
            },
            {
                "image_url": "<https://source.unsplash.com/random/305*300>",
                "title" : "이미지3",
                "contents" : "컨텐츠3",
                "type": "image",
                "href": "<https://source.unsplash.com/random/306*300>"
            }
        ],
        "buttons": [
            {
                "label": "이미지1",
                "type" : "image",
                "href": "<https://source.unsplash.com/random/307*300>"
            },
            {
                "label": "이미지2",
                "type" : "image",
                "href": "<https://source.unsplash.com/random/308*300>"
            },
            {
                "label": "이미지3",
                "type" : "image",
                "href": "<https://source.unsplash.com/random/309*300>"
            }
        ],
        "button_layout" : "vertical"
    }
}

필드	속성	필수여부	설명	예시	비고
whole	boolean	X	전체 전송 여부	false
to	array	whole이 false이거나 없는 경우 O	받는 대상 유저의 이메일 값	[”[e-mail]”, “[e-mail]”]
type	string	X	서비스 알림의 타입	“default”
template	string	X	서비스 알림의 레이아웃	“text”
items	array	O	서비스 알림의 레이아웃 요소
items.header	string	O	list template의 header	“헤더입니다.”	50자
items.items	array	O	list template의 요소		static 타입인 경우 최대 5개
items.items.image_url	string	X	list template의 이미지 url	“https://source.unsplash.com/random/300*300”
items.items.title	string	O	list template의 제목	“타이틀1입니다.”	50자
items.items.contents	string	X	list template의 내용	“컨텐츠1입니다.”	200자
items.items.type	string	href 있으면 O	list template의 클릭 타입	“image”	image, link
items.items.href	string	type 있으면 O	list template의 클릭 시 참조하는 링크 또는 코드 값	“https://source.unsplash.com/random/300*300”
items.buttons	array	X	card template의 버튼		버튼 최대 3개
items.buttons.label	string	O	버튼에 쓰여진 글자	“이미지1”	vertical : 14자 horizontal : 8자
items.buttons.type	string	O	버튼 타입	“image”	image, link, webview
items.buttons.href	string	O	버튼 클릭 했을 때 참조하는 링크 또는 코드 값	“https://source.unsplash.com/random/300*300”
items.button_layout	string	X	버튼 배치방식	“vertical”	vertical, horizontal

슬라이드 텍스트형 서비스알림

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["[e-mail]"],
    "template": "text",
    "type": "carousel",
    "important": false,
    "items":
    [
        {
            "header": "헤더1",
            "contents" : "컨텐츠 1",
            "buttons": [
                {
                    "label": "이미지1",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/301*300>"
                },
                {
                    "label": "이미지2",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/302*300>"
                },
                {
                    "label": "이미지3",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/303*300>"
                }
            ]
        },
        {
            "header": "헤더2",
            "contents" : "컨텐츠2",
            "buttons": [
                {
                    "label": "이미지1",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/304*300>"            },
                {
                    "label": "이미지2",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/200*300>"
                },
                {
                    "label": "이미지3",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/100*300>"
                }
            ]
        },
        {
            "header": "헤더3",
            "contents" : "컨텐츠3",
            "buttons": [
                {
                    "label": "naver",
                    "type" : "link",
                    "href": "<http://www.naver.com>"
                },
                {
                    "label": "google",
                    "type" : "link",
                    "href": "<http://www.google.com>"
                },
                {
                    "label": "stackoverflow",
                    "type" : "link",
                    "href": "<https://stackoverflow.com/>"
                }
            ],
            "button_layout" : "vertical"
        }
    ]
}

필드	속성	필수여부	설명	예시	비고
whole	boolean	X	전체 전송 여부	false
to	array	whole이 false이거나 없는 경우 O	받는 대상 유저의 이메일 값	[”[e-mail]”, “[e-mail]”]
type	string	X	서비스 알림의 타입	“default”
template	string	X	서비스 알림의 레이아웃	“text”
items	array	O	서비스 알림의 레이아웃 요소
items.*.header	string	X	text template의 header	“헤더입니다”	50자
items.*.contents	string	O	text template의 contents	“컨텐츠입니다”	1000자
items.*.buttons	array	X	text template의 버튼		버튼 최대 3개
items.*.buttons.label	string	O	버튼에 쓰여진 글자	“이미지”
items.*.buttons.type	string	O	버튼 타입	“image”	image, link, webview
items.*.buttons.href	string	O	버튼 클릭 했을 때 참조하는 링크 또는 코드 값	“https://source.unsplash.com/random/300*300"
items.*.button_layout	string	X	버튼 배치방식	“vertical”	vertical 고정

슬라이드 카드형 서비스알림

Untitled

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["[e-mail]"],
    "template": "card",
    "type": "carousel",
    "important": false,
    "items": 
    [
        {
            "title" : "타이틀1",
            "contents" : "컨텐츠1",
            "image_url": "<https://source.unsplash.com/random/600*300>",
            "buttons": [
                {
                    "label": "이미지1",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/311*300>"
                },
                {
                    "label": "이미지2",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/310*300>"
                },
                {
                    "label": "이미지3",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/312*300>"
                }
            ],
            "button_layout" : "vertical"
        },
        {
            "title" : "타이틀2",
            "contents" : "컨텐츠2",
            "image_url": "<https://source.unsplash.com/random/500*300>",
            "buttons": [
                {
                    "label": "이미지1",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/313*300>"            },
                {
                    "label": "이미지2",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/213*300>"
                },
                {
                    "label": "이미지3",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/113*300>"
                }
            ],
            "button_layout" : "vertical"
        },
        {
            "title" : "타이틀3",
            "contents" : "컨텐츠3",
            "image_url": "<https://source.unsplash.com/random/414*300>",
            "buttons": [
                {
                    "label": "naver",
                    "type" : "link",
                    "href": "<http://www.naver.com>"
                },
                {
                    "label": "google",
                    "type" : "link",
                    "href": "<http://www.google.com>"
                },
                {
                    "label": "stackoverflow",
                    "type" : "link",
                    "href": "<http://stackoverflow.com>"
                }
            ],
            "button_layout" : "vertical"
        }
    ]
}

필드	속성	필수여부	설명	예시	비고
whole	boolean	X	전체 전송 여부	false
to	array	whole이 false이거나 없는 경우 O	받는 대상 유저의 이메일 값	[”[e-mail]”, “[e-mail]”]
type	string	X	서비스 알림의 타입	“default”
template	string	X	서비스 알림의 레이아웃	“text”
items	array	O	서비스 알림의 레이아웃 요소
items.title	string	O	card template의 header	“헤더입니다”	100자
items.contents	string	X	card template의 contents	“컨텐츠입니다”	1000자
items.image_url	string	O	card template의 이미지 url	“https://source.unsplash.com/random/300*300”
items.buttons	array	X	card template의 버튼		버튼 최대 3개
items.buttons.label	string	O	버튼에 쓰여진 글자	“이미지”
items.buttons.type	string	O	버튼 타입	“image”	image, link, webview
items.buttons.href	string	O	버튼 클릭 했을 때 참조하는 링크 또는 코드 값	“https://source.unsplash.com/random/300*300”
items.button_layout	string	X	버튼 배치방식		vertical 고정

슬라이드 리스트형 서비스알림

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["[e-mail]"],
    "template": "list",
    "type": "carousel",
    "important": false,
    "items": 
    [
        {
            "header": "헤더1",
            "items": [
                {
                    "image_url": "<https://source.unsplash.com/random/100*100>",
                    "title" : "타이틀1",
                    "contents" : "컨텐츠1",
                    "type": "image",
                    "href": "<https://source.unsplash.com/random/111*300>"
                },
                {
                    "image_url": "<https://source.unsplash.com/random/222*100>",
                    "title" : "타이틀2",
                    "contents" : "컨텐츠2",
                    "type": "image",
                    "href": "<https://source.unsplash.com/random/300*345>"
                },
                {
                    "image_url": "<https://source.unsplash.com/random/333*100>",
                    "title" : "타이틀3",
                    "contents" : "컨텐츠3",
                    "type": "image",
                    "href": "<https://source.unsplash.com/random/300*346>"
                },
                {
                    "image_url": "<https://source.unsplash.com/random/444*200>",
                    "title" : "타이틀4",
                    "contents" : "컨텐츠4",
                    "type": "image",
                    "href": "<https://source.unsplash.com/random/300*347>"
                }
            ],
            "buttons": [
                {
                    "label": "이미지1",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/300*348>"
                },
                {
                    "label": "이미지2",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/300*349>"
                },
                {
                    "label": "이미지3",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/300*351>"
                }
            ],
            "button_layout" : "vertical"
        },
        {
            "header": "헤더2",
            "items": [
                {
                    "image_url": "<https://source.unsplash.com/random/555*100>",
                    "title" : "이미지1",
                    "contents" : "컨텐츠1",
                    "type": "image",
                    "href": "<https://source.unsplash.com/random/666*101>"
                },
                {
                    "image_url": "<https://source.unsplash.com/random/777*200>",
                    "title" : "이미지2",
                    "contents" : "컨텐츠2",
                    "type": "image",
                    "href": "<https://source.unsplash.com/random/150*102>"
                },
                {
                    "image_url": "<https://source.unsplash.com/random/151*300>",
                    "title" : "이미지3",
                    "contents" : "컨텐츠3",
                    "type": "image",
                    "href": "<https://source.unsplash.com/random/152*103>"
                }
            ],
            "buttons": [
                {
                    "label": "이미지4",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/153*104>"
                },
                {
                    "label": "이미지5",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/154*105>"
                },
                {
                    "label": "이미지6",
                    "type" : "image",
                    "href": "<https://source.unsplash.com/random/155*106>"
                }
            ],
            "button_layout" : "vertical"
        },
        {
            "header": "헤더3",
            "items": [
                {
                    "image_url": "<https://source.unsplash.com/random/156*301>",
                    "title" : "naver",
                    "contents" : "컨텐츠1",
                    "type": "link",
                    "href": "<http://www.naver.com>"
                },
                {
                    "image_url": "<https://source.unsplash.com/random/157*302>",
                    "title" : "google",
                    "contents" : "컨텐츠2",
                    "type": "link",
                    "href": "<http://www.google.com>"
                },
                {
                    "image_url": "<https://source.unsplash.com/random/158*303>",
                    "title" : "so",
                    "contents" : "컨텐츠3",
                    "type": "link",
                    "href": "<http://stackoverflow.com>"
                }
            ],
            "buttons": [
                {
                    "label": "Naver",
                    "type" : "link",
                    "href": "<http://www.naver.com>"
                },
                {
                    "label": "google",
                    "type" : "link",
                    "href": "<http://www.google.com>"
                },
                {
                    "label": "stackoverflow",
                    "type" : "link",
                    "href": "<http://stackoverflow.com>"
                }
            ],
            "button_layout" : "vertical"
        }
    ]
}

필드	속성	필수여부	설명	예시	비고
whole	boolean	X	전체 전송 여부	false
to	array	whole이 false이거나 없는 경우 O	받는 대상 유저의 이메일 값	[”[e-mail]”, “[e-mail]”]
type	string	X	서비스 알림의 타입	“default”
template	string	X	서비스 알림의 레이아웃	“text”
items	array	O	서비스 알림의 레이아웃 요소
items.*.header	string	O	list template의 header	“헤더입니다.”	50자
items.*.items	array	O	list template의 요소		carousel인 경우 최대 4개
items.*.items.image_url	string	X	list template의 이미지 url	“https://source.unsplash.com/random/300*300”
items.*.items.title	string	O	list template의 제목	“타이틀1입니다.”	50자
items.*.items.contents	string	X	list template의 내용	“컨텐츠1입니다.”	200자
items.*.items.type	string	href 있으면 O	list template의 클릭 타입	“image”	image, link
items.*.items.href	string	type 있으면 O	list template의 클릭 시 참조하는 링크 또는 코드 값	“https://source.unsplash.com/random/300*300”
items.*.buttons	array	X	card template의 버튼		버튼 최대 3개
items.*.buttons.label	string	O	버튼에 쓰여진 글자	“이미지1”
items.*.buttons.type	string	O	버튼 타입	“image”	image, link, webview
items.*.buttons.href	string	O	버튼 클릭 했을 때 참조하는 링크 또는 코드 값	“https://source.unsplash.com/random/300*300”
items.*.button_layout	string	X	버튼 배치방식	“vertical”	vertical 고정

• href는 버튼을 클릭 했을 때 참조하는 링크 또는 코드 값입니다.

버튼 레이아웃

• horizontal

• vertical

• 버튼 레이아웃의 제한사항은 다음과 같습니다.

1. "vertical" (세로배치) 혹은 "horizontal" (가로배치) 만 입력 가능합니다.

2. 단일형만 button layout 설정 가능, 케로셀형은 세로배치 고정입니다.

3. 단일형에서 별도 지정하지 않는 경우 버튼 개수에 따라 배치모양이 결정됩니다. 2개 이하: 가로배치 3개: 세로 배치

4. 버튼 레이아웃에 따른 버튼명 글자 수 제한은 다음과 같습니다. vertical 레이아웃 : button label 14자, horizontal 레이아웃 : button label 8자

1. 레이아웃에 따른 버튼명 글자 수 제한은 다음과 같습니다. vertical 레이아웃 : button label 14자, horizontal 레이아웃 : button label 8자

사이즈 제한

type	template	속성	사이즈 제한
static / carousel	text	header	50자
static / carousel	text	contents	1,000자
static / carousel	card	title	100자
static / carousel	card	contents	1,000자
static / carousel	list	header	50자
static / carousel	list	title	50자
static / carousel	list	contents	200자

글자수 제한을 넘어서도 요청을 받지 않는게 아닌 저 글자수만큼만 잘라서 처리합니다.

상태 코드

HTTP 응답 코드는 일반적인 성공과 오류 클래스를 나타내는 데 사용됩니다.

성공 코드

HTTP 상태	설명
200	성공적으로 처리된 요청

오류 코드

HTTP 상태명	code	message
403	invalid_request	잘못된 요청입니다.
410	invalid_contract	유효하지 않는 계약입니다.
419	invalid_token	만료된 토큰입니다.
422	invalid_parameter	유효하지 않는 요청 파라미터입니다.