통합메시지

메시지 별로 Fallback을 순차적으로 처리해주는 통합메시지 발송 규격입니다.

• 메시지 관련 상세 옵션필드를 모두 사용할 수 있는 전문가 방식 입니다.

• 요청 당 최대 10개의 수신번호를 함께 전송할 수 있습니다.

• 메시지 내용, 제목, 버튼 등에 치환문구를 활용하여 전송 할 수 있습니다.

• 전체 메시지 정보를 입력하는 방식 또는 사전에 등록한 메시지 폼을 이용하는 방식, 총 2가지 방식 중 선택하여 전송하실 수 있습니다.

• 상세 Response 내용은 코드표를 참조해주시기 바랍니다.

messageFlow 필드에 담기는 메시지 순서대로 전송 처리 후 실패 시 다음 메시지로 Fallback 처리 됩니다.

통합메시지 전송

POST /v1/send/omni

Request

Header

Name	Type	Description
Authorization	String	schema + “ “ + token
Content-Type	String	application/json
Accept	String	application/json

Body

Name	Type	Required	Description
destinations	Object Array	YES	수신 정보 리스트(최대 10개)
messageFlow	Object Array	NO	메시지 정보 리스트
messageForm	String	NO	메시지 폼 ID
paymentCode	String(20)	NO	정산용 부서코드
ref	String(200)	NO	참조필드

cURL

curl -X POST https://omni.ibapi.kr/v1/send/omni \
-H "content-type: application/json" \
-H "Accept: application/json" \
-H "Authorization:Bearer 발급받은 토큰" \
-d '{"messageFlow":[{"rcs":{"content":{"standalone":{"text":"RCS 메시지 내용"}},"from":"발신번호","formatId":"SS000000", "brandKey":"RCS브랜드키"}},{"sms":{"from":"발신번호","text":"SMS 메시지 내용"}}],"destinations":[{"to":"수신번호"}],"ref":"참조필드"}' 

JAVA

import java.io.*;
import okhttp3.*;
public class Main {
  public static void main(String []args) throws IOException{
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\"messageFlow\":[{\"rcs\":{\"content\":{\"standalone\":{\"text\":\"RCS 메시지 내용\"}},\"from\":\"발신번호\",\"formatId\":\"SS000000\", \"brandKey\":\"RCS브랜드키\"}},{\"sms\":{\"from\":\"발신번호\",\"text\":\"SMS 메시지 내용\"}}],\"destinations\":[{\"to\":\"수신번호\"}],\"ref\":\"참조필드\"}");
    Request request = new Request.Builder()
      .url("https://omni.ibapi.kr/v1/send/omni")
      .method("POST", body)
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("Authorization", "Bearer 발급받은 토큰")
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}

Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://omni.ibapi.kr/v1/send/omni"
  method := "POST"

  payload := strings.NewReader(`{"messageFlow":[{"rcs":{"content":{"standalone":{"text":"RCS 메시지 내용"}},"from":"발신번호","formatId":"SS000000", "brandKey":"RCS브랜드키"}},{"sms":{"from":"발신번호","text":"SMS 메시지 내용"}}],"destinations":[{"to":"수신번호"}],"ref":"참조필드"}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Authorization", "Bearer 발급받은 토큰")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://omni.ibapi.kr/v1/send/omni',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{"messageFlow":[{"rcs":{"content":{"standalone":{"text":"RCS 메시지 내용"}},"from":"발신번호","formatId":"SS000000", "brandKey":"RCS브랜드키"}},{"sms":{"from":"발신번호","text":"SMS 메시지 내용"}}],"destinations":[{"to":"수신번호"}],"ref":"참조필드"}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer 발급받은 토큰'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

NodeJS

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://omni.ibapi.kr/v1/send/omni',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer 발급받은 토큰'
  },
  body: JSON.stringify({
    "messageFlow": [
      {
        "rcs": {
          "content": {
            "standalone": {
              "text": "RCS 메시지 내용"
            }
          },
          "from": "발신번호",
          "formatId": "SS000000",
          "brandKey":"RCS브랜드키"
        }
      },
      {
        "sms": {
          "from": "발신번호",
          "text": "SMS 메시지 내용"
        }
      }
    ],
    "destinations": [
      {
        "to": "수신번호"
      }
    ],
    "ref": "참조필드"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://omni.ibapi.kr/v1/send/omni");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer 발급받은 토큰");
var content = new StringContent("{\"messageFlow\":[{\"rcs\":{\"content\":{\"standalone\":{\"text\":\"RCS 메시지 내용\"}},\"from\":\"발신번호\",\"formatId\":\"SS000000\", \"brandKey\":\"RCS브랜드키\"}},{\"sms\":{\"from\":\"발신번호\",\"text\":\"SMS 메시지 내용\"}}],\"destinations\":[{\"to\":\"수신번호\"}],\"ref\":\"참조필드\"}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

JavaScript

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer 발급받은 토큰");

var raw = JSON.stringify({
  "messageFlow": [
    {
      "rcs": {
        "content": {
          "standalone": {
            "text": "RCS 메시지 내용"
          }
        },
        "from": "발신번호",
        "formatId": "SS000000",
        "brandKey":"RCS브랜드키"
      }
    },
    {
      "sms": {
        "from": "발신번호",
        "text": "SMS 메시지 내용"
      }
    }
  ],
  "destinations": [
    {
      "to": "수신번호"
    }
  ],
  "ref": "참조필드"
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://omni.ibapi.kr/v1/send/omni", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

python

import http.client
import json

conn = http.client.HTTPSConnection("omni.ibapi.kr")
payload = json.dumps({
  "messageFlow": [
    {
      "rcs": {
        "content": {
          "standalone": {
            "text": "RCS 메시지 내용"
          }
        },
        "from": "발신번호",
        "formatId": "SS000000",
        "brandKey":"RCS브랜드키"
      }
    },
    {
      "sms": {
        "from": "발신번호",
        "text": "SMS 메시지 내용"
      }
    }
  ],
  "destinations": [
    {
      "to": "수신번호"
    }
  ],
  "ref": "참조필드"
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer 발급받은 토큰'
}
conn.request("POST", "/v1/send/omni", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Ruby

require "uri"
require "json"
require "net/http"

url = URI("https://omni.ibapi.kr/v1/send/omni")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Accept"] = "application/json"
request["Authorization"] = "Bearer 발급받은 토큰"
request.body = JSON.dump({
  "messageFlow": [
    {
      "rcs": {
        "content": {
          "standalone": {
            "text": "RCS 메시지 내용"
          }
        },
        "from": "발신번호",
        "formatId": "SS000000",
        "brandKey":"RCS브랜드키"
      }
    },
    {
      "sms": {
        "from": "발신번호",
        "text": "SMS 메시지 내용"
      }
    }
  ],
  "destinations": [
    {
      "to": "수신번호"
    }
  ],
  "ref": "참조필드"
})

response = https.request(request)
puts response.read_body

Response

Header

Name	Type	Description
Content-Type	String	application/json

Body

Name	Type	Description
code	String(4)	API호출 결과 코드
result	String	API호출 결과 설명
data	Object	API호출 결과 데이터
ref	String(200)	참조필드(요청 시 입력한 데이터)

HTTP 200(성공:Success)

{
    "code": "A000",
    "result": "Success",
    "data": {
             "destinations":[
                   {
                    "to": "01000000000",
                    "msgKey": "발급된 메시지키",
                    "code": "A000",
                    "result": "Success"
                   }
             ]
    },
    "ref": "요청시 입력한 데이터"
}

HTTP 400(실패:Bad Request)

{
    "code": "A010",
    "result": "Cannot parse JSON"
} 

HTTP 401(실패:Unauthorized)

{
    "code": "A001",
    "result": "Expired token"
}

HTTP 429(실패:Too Many Requests)

{
    "code": "A020",
    "result": "Rate limit exceeded"
}

HTTP 500(실패:Forbidden)

{
    "code": "A999",
    "result": "Unknown error"
}

Schema

destinations

최대 10개 수신정보를 함께 전송할 수 있습니다.

Name	Type	Required	Description
to	String	YES	수신번호
replaceWords	Object	NO	치환 문구(JSON)

messageFlow

Array 순서대로 전송, Fallback 처리 됩니다.

Name	Type	Required	Description
sms	Object	NO	SMS 메시지 정보
mms	Object	NO	MMS 메시지 정보
rcs	Object	NO	RCS 메시지 정보
alimtalk	Object	NO	카카오 알림톡 메시지 정보
friendtalk	Object	NO	카카오 친구톡 메시지 정보

sms

SMS 메시지 정보입니다.

Name	Type	Required	Description
from	String	YES	발신번호
text	String(90)	YES	SMS 메시지 내용(90byte)
ttl	String	NO	메시지 유효 시간(초), Default:86400
originCID	String(9)	NO	최초 발신사업자 식별코드

mms

MMS 메시지 정보입니다.

Name	Type	Required	Description
from	String	YES	발신번호
text	String(2000)	YES	MMS 메시지 내용(2000byte)
title	String(40)	NO	MMS 메시지 제목(40byte)
fileKey	String Array	NO	파일 키(최대 3개)
ttl	String	NO	메시지 유효 시간(초)(Default:86400)
originCID	String(9)	NO	최초 발신사업자 식별코드

rcs

RCS 메시지 정보입니다.

Name	Type	Required	Description
from	String	YES	발신번호
content	Object	YES	RCS Message Json Object
formatId	String	YES	RCS 메시지 formatID
brandKey	String	YES	RCS 브랜드 키
brandId	String	NO	RCS 브랜드 ID
groupId	String	NO	RCS 메시지 그룹ID
expiryOption	String(1)	NO	전송 time out설정 (Default: 1) (1: 24시간, 2: 40초, 3: 3분 10초, 4: 1시간)
copyAllowed	String(1)	NO	메시지 복사 허용 여부(Default:0) (0: 불가, 1:허용)
header	String(1)	NO	메시지 상단 ‘광고’ 표출 여부 (Default: 0) (0:미표출, 1:표출) 1인경우 footer 입력 필요
footer	String(100)	NO	메시지 하단 수신거부 번호
agencyId	String	NO	대행사ID (Default: infobank)
agencyKey	String	NO	대행사 키
ttl	String	NO	메시지 유효 시간(초)(Default:86400)

alimtalk

카카오 알림톡 메시지 정보입니다.

Name	Type	Required	Description
senderKey	String	YES	카카오 비즈메시지 발신 프로필 키
msgType	String	YES	카카오 비즈메시지 타입
templateCode	String	YES	알림톡 템플릿 코드
text	String(1000)	YES	알림톡 내용
title	String(50)	NO	알림톡 제목(강조표기형 템플릿)
attachment	Object	NO	첨부 정보
supplement	Object	NO	부가 정보
price	String	NO	메시지 에 포함된 가격/금액/결제금액
currencyType	String	NO	메시지에 포함된 가격/금액/결제금액의 통화 단위 (국제 통화 코드 - KRW, USD, EUR)

friendtalk

카카오 친구톡 메시지 정보입니다.

Name	Type	Required	Description
senderKey	String	YES	카카오 비즈메시지 발신 프로필 키
msgType	String	YES	카카오 비즈메시지 타입
text	String(1000)	YES	친구톡 내용
attachment	Object	NO	첨부 정보
adFlag	String	NO	광고 거부 사용 여부(Y/N)

attachment(알림톡)

카카오 알림톡 첨부정보입니다.

Name	Type	Required	Description
button	Object Array	NO	버튼 정보
item	Object	NO	아이템 정보
itemHighlight	Object	NO	아이템 하이라이트 정보

attachment(친구톡)

카카오 친구톡 첨부정보입니다.

Name	Type	Required	Description
button	Object Array	NO	버튼 정보
item	Object	NO	아이템 정보
image	Object	NO	친구톡 이미지 정보

supplement

카카오 비즈메시지 부가정보입니다.

Name	Type	Required	Description
quickReply	Object Array	NO	바로연결 정보

item

카카오 비즈메시지 아이템정보입니다.

Name	Type	Required	Description
list	Object Array	YES	아이템 리스트(2~10 개)
summary	Object	NO	아이템 요약정보

list

아이템 리스트입니다.

Name	Type	Required	Description
title	String(6)	YES	타이틀
description	String(23)	YES	부가정보

summary

아이템 요약정보입니다.

Name	Type	Required	Description
title	String(6)	YES	타이틀
description	String(14)	YES	가격정보 허용되는 문자: 통화기호(유니코드 통화기호, 元, 円, 원), 통화코드(ISO 4217), 숫자, 콤마, 소 수점, 공백 소수점 2 자리까지 허용

itemHighlight

아이템 하이라이트 정보입니다.

Name	Type	Required	Description
title	String(30)	YES	타이틀(이미지가 있는 경우 최대 21 자)
description	String(19)	YES	부가정보(이미지가 있는 경우 최대 13 자)

image

친구톡 이미지 정보입니다.

Name	Type	Required	Description
imgUrl	String	YES	등록한 이미지 URL
imgLink	String	NO	이미지 클릭 시 이동할 URL 미 설정 시 카카오 톡 내 이미지 뷰어 사용

data

Name	Type	Description
destinations	Object Array Name Type Description to String 수신번호 msgKey String 메시지 키 code String 접수 결과 코드 result String 접수 결과 설명	수신 정보 별 접수 결과

button

Name	Type	Required	Description
type	String	YES	카카오 버튼 종류
name	String	YES	카카오 버튼 명
urlPc	String	NO	PC 환경에서 버튼 클릭시 이동할 URL
urlMobile	String	NO	모바일 환경에서 버튼 클릭 시 이동할 URL
schemeIos	String	NO	iOS 환경에서 버튼클릭 시 실행할 application custom scheme
schemeAndroid	String	NO	Android 환경에서 버튼클릭 시 실행 할 application custom scheme
target	String	NO	버튼 type이 WL(웹 링크)일 경우 "target":"out"입력 시 아웃링크 사용
chatExtra	String	NO	봇/상담톡전환 시 전달할 메타정보
chatEvent	String	NO	봇/상담톡 전환 시 연결할 이벤트 명
bizFormKey	String	NO	비즈폼 키
bizFormId	String	NO	비즈폼 ID

카카오 버튼 타입(type)

Code	Button type	Related field(Required)	Description
WL	웹 링크	urlMobile (Y) urlPc(N)	버튼 클릭 시 이동할 pc/mobile환경별 web url
AL	앱 링크	schemeAndroid(Y) schemeIos(N) urlMobile(N) urlPc(N)	scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력
BK	봇 키워드	-	해당 버튼 텍스트 전송
MD	메시지 전달	-	해당 버튼 텍스트 + 메시지 본문 전송
DS	배송조회	-	버튼 클릭 시 배송 조회 페이지로 이동
BC	상담톡 전환	chatExtra(N)	상담톡을 이용하는 카카오톡 채널만 이용 가능
BT	챗봇 전환	chatExtra(N) chatEvent(N)	카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능
AC	채널 추가	-	버튼 클릭 시 카카오톡 채널 추가
P1	플러그인#1	-	이미지 보안 전송 플러그인
P2	플러그인#2	-	개인정보이용 플러그인
P3	플러그인#3	-	원클릭 결제 플러그인 (발송시 oneclick_id 또는 product_id를 필수로 전달해아 함)
BF	비즈폼	bizFormKey(N) bizFormId(N)	카카오 비즈니스에서 생성한 비즈니스폼 ID

카카오 메시지 타입(msgtype)

Code	Message type	Description
AT	알림톡	일반 알림톡 템플릿 사용 시 설정
AI	알림톡 이미지	이미지 알림톡 템플릿 사용 시 설정
FT	친구톡	일반 친구톡 메시지 전송 시 설정
FI	친구톡 이미지	이미지 친구톡 메시지 전송 시 설정
FW	친구톡 와이드 이미지	와이드 이미지 친구톡 메시지 전송 시 설정

quickReply

카카오 비즈메시지 바로연결 정보입니다.

Name	Type	Required	Description
type	String	YES	바로연결 타입
name	String	YES	바로연결 제목(최대 14자)
urlPc	String	NO	PC 환경에서 버튼 클릭 시 이동할 URL
urlMobile	String	NO	모바일 환경에서 버튼 클릭 시 이동할 URL
schemeIos	String	NO	IOS 환경에서 버튼 클릭 시 실행할 커스텀 scheme
schemeAndroid	String	NO	Android 환경에서 버튼 클릭 시 실행할 커스텀 scheme
chatExtra	String	NO	봇/상담톡 전환 시 전달할 메타정보
chatEvent	String	NO	봇/상담톡 전환 시 연결할 봇 이벤트명
bizFormId	String	NO	비즈폼 ID

카카오 바로연결 타입(type)

Code	Button type	Related field(Required)	Description
WL	웹 링크	urlMobile (Y) urlPc(N)	버튼 클릭 시 이동할 pc/mobile환경별 web url
AL	앱 링크	schemeAndroid(Y) schemeIos(N) urlMobile(N) urlPc(N)	scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력
BK	봇 키워드	-	해당 버튼 텍스트 전송
BC	상담톡 전환	chatExtra(N)	상담톡을 이용하는 카카오톡 채널만 이용 가능
BT	챗봇 전환	chatExtra(N) chatEvent(N)	카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능
BF	비즈폼	bizFormId(Y)	카카오 비즈니스에서 생성한 비즈니스폼 ID

참고사항

최초 발신사업자 식별코드(originCID)

인터넷 문자 전송 시 최초 발신사업자를 특정하기 위해 삽입하는 식별코드이며, 특수한 유형의 부가통신사업자 등록번호(9자리 숫자)를 사용합니다.

최초 발신사업자가 재판매사업자이면 최초 재판매사업자 등록번호가 수록되고, 재판매사업자를 통하지 않고 문자중계사로 발송할 경우 문자중계사의 등록번호가 수록됩니다.

예1)기업 → 재판매사업자1 → 재판매사업자 2 → 문자중계사 → 이동통신사 재판매사업자1의 등록번호가 삽입

예2)기업 → 문자중계사 → 이동통신사 문자중계사의 등록번호가 삽입

치환 문구, 치환 전송 (replaceWords)

메시지 내용 및 제목 등에 #{key} 형태로 치환 예약어를 지정합니다. 수신정보(destinations)에 replaceWords 에 치환될 값을 JSON형태로 입력합니다. 예){"key":"value"} 실제 단말에서는 value 값으로 치환된 메시지가 전송 됩니다.