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

기본 정보

서비스 봇 등록 최대 개수

20개(기본 봇 제외)
기본 봇이란? 오피스넥스트에서 제공하는 시스템 봇

시작하기

이 문서는 오피스넥스트 메신저 서비스 알림 전송 API를 이해하고 설정하는데 도움을 드리기 위한 가이드입니다.

규칙

API 설정은 메신저 관리자 페이지(바로가기)에서 제공됩니다.
- 경로: 메신저 관리자 페이지 > 관리 메뉴 > Webhook
서비스 알림 전송 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에 담아서 요청하면 예시 사진과 같이 표시되게 됩니다.

사용 예시

기본 텍스트형 서비스알림

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

필드

속성

필수여부

설명

예시

whole

boolean

전체 전송 여부

false

to

array

whole이 false이거나 없는 경우 O

받는 대상 유저의 이메일 값

[”example1@jiran.com”, “example2@jiran.com”]

contents

string

서비스 알림의 본문 내용

“컨텐츠입니다.”

type

string

서비스 알림의 타입

“default”

template

string

서비스 알림의 레이아웃

“text”

버튼 텍스트형 서비스알림

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["example@jiran.com"],
    "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

전체 전송 여부

false

to

array

whole이 false이거나 없는 경우 O

받는 대상 유저의 이메일 값

[”example1@jiran.com”, “example2@jiran.com”]

type

string

서비스 알림의 타입

“default”

template

string

서비스 알림의 레이아웃

“text”

items

array

서비스 알림의 레이아웃 요소

items.header

string

text template의 header

“헤더입니다”

50자

items.contents

string

text template의 contents

“컨텐츠입니다”

1000자

items.buttons

array

text template의 버튼

버튼 최대 3개

items.buttons.label

string

버튼에 쓰여진 글자

“이미지 보기”

vertical: 14자 horizontal: 8자

items.buttons.type

string

버튼 타입

“image”

image, link, webview

items.buttons.href

string

버튼 클릭 했을 때 참조하는 링크 또는 코드 값

“https://source.unsplash.com/random/300*300"

items.button_layout

string

버튼 배치방식

“vertical”

vertical, horizontal

버튼 카드형 서비스알림

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["example@jiran.com"],
    "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

전체 전송 여부

false

to

array

whole이 false이거나 없는 경우 O

받는 대상 유저의 이메일 값

[”example1@jiran.com”, “example2@jiran.com”]

type

string

서비스 알림의 타입

“default”

template

string

서비스 알림의 레이아웃

“text”

items

array

서비스 알림의 레이아웃 요소

items.header

string

list template의 header

“헤더입니다.”

50자

items.items

array

list template의 요소

static 타입인 경우 최대 5개

items.items.image_url

string

list template의 이미지 url

“https://source.unsplash.com/random/300*300”

items.items.title

string

list template의 제목

“타이틀1입니다.”

50자

items.items.contents

string

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

card template의 버튼

버튼 최대 3개

items.buttons.label

string

버튼에 쓰여진 글자

“이미지1”

vertical : 14자 horizontal : 8자

items.buttons.type

string

버튼 타입

“image”

image, link, webview

items.buttons.href

string

버튼 클릭 했을 때 참조하는 링크 또는 코드 값

“https://source.unsplash.com/random/300*300”

items.button_layout

string

버튼 배치방식

“vertical”

vertical, horizontal

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

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["example@jiran.com"],
    "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

전체 전송 여부

false

to

array

whole이 false이거나 없는 경우 O

받는 대상 유저의 이메일 값

[”example1@jiran.com”, “example2@jiran.com”]

type

string

서비스 알림의 타입

“default”

template

string

서비스 알림의 레이아웃

“text”

items

array

서비스 알림의 레이아웃 요소

items.*.header

string

text template의 header

“헤더입니다”

50자

items.*.contents

string

text template의 contents

“컨텐츠입니다”

1000자

items.*.buttons

array

text template의 버튼

버튼 최대 3개

items.*.buttons.label

string

버튼에 쓰여진 글자

“이미지”

items.*.buttons.type

string

버튼 타입

“image”

image, link, webview

items.*.buttons.href

string

버튼 클릭 했을 때 참조하는 링크 또는 코드 값

“https://source.unsplash.com/random/300*300"

items.*.button_layout

string

버튼 배치방식

“vertical”

vertical 고정

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

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["example@jiran.com"],
    "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

전체 전송 여부

false

to

array

whole이 false이거나 없는 경우 O

받는 대상 유저의 이메일 값

[”example1@jiran.com”, “example2@jiran.com”]

type

string

서비스 알림의 타입

“default”

template

string

서비스 알림의 레이아웃

“text”

items

array

서비스 알림의 레이아웃 요소

items.title

string

card template의 header

“헤더입니다”

100자

items.contents

string

card template의 contents

“컨텐츠입니다”

1000자

items.image_url

string

card template의 이미지 url

“https://source.unsplash.com/random/300*300”

items.buttons

array

card template의 버튼

버튼 최대 3개

items.buttons.label

string

버튼에 쓰여진 글자

“이미지”

items.buttons.type

string

버튼 타입

“image”

image, link, webview

items.buttons.href

string

버튼 클릭 했을 때 참조하는 링크 또는 코드 값

“https://source.unsplash.com/random/300*300”

items.button_layout

string

버튼 배치방식

vertical 고정

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

<https://api.officewave.co.kr/api/v1/hooks/{token}/notifications> / POST 
{
    "to": ["example@jiran.com"],
    "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

전체 전송 여부

false

to

array

whole이 false이거나 없는 경우 O

받는 대상 유저의 이메일 값

[”example1@jiran.com”, “example2@jiran.com”]

type

string

서비스 알림의 타입

“default”

template

string

서비스 알림의 레이아웃

“text”

items

array

서비스 알림의 레이아웃 요소

items.*.header

string

list template의 header

“헤더입니다.”

50자

items.*.items

array

list template의 요소

carousel인 경우 최대 4개

items.*.items.image_url

string

list template의 이미지 url

“https://source.unsplash.com/random/300*300”

items.*.items.title

string

list template의 제목

“타이틀1입니다.”

50자

items.*.items.contents

string

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

card template의 버튼

버튼 최대 3개

items.*.buttons.label

string

버튼에 쓰여진 글자

“이미지1”

items.*.buttons.type

string

버튼 타입

“image”

image, link, webview

items.*.buttons.href

string

버튼 클릭 했을 때 참조하는 링크 또는 코드 값

“https://source.unsplash.com/random/300*300”

items.*.button_layout

string

버튼 배치방식

“vertical”

vertical 고정

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

버튼 레이아웃

horizontal

vertical

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

"vertical" (세로배치) 혹은 "horizontal" (가로배치) 만 입력 가능합니다.
단일형만 button layout 설정 가능, 케로셀형은 세로배치 고정입니다.
단일형에서 별도 지정하지 않는 경우 버튼 개수에 따라 배치모양이 결정됩니다. 2개 이하: 가로배치 3개: 세로 배치
버튼 레이아웃에 따른 버튼명 글자 수 제한은 다음과 같습니다. vertical 레이아웃 : button label 14자, horizontal 레이아웃 : button label 8자

레이아웃에 따른 버튼명 글자 수 제한은 다음과 같습니다. 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

유효하지 않는 요청 파라미터입니다.

Previous고객지원 Next메신저 메시지 전송 가이드

Last updated 1 month ago