팝빌 커넥트 서비스

팝빌 커넥트 서비스란 카카오톡 전송결과를 실시간으로 확인할 수 있는 웹훅 수신(Webhook Incoming) 서비스입니다. 카카오톡 전송을 요청한 시점부터 수신 단말기기가 카카오톡을 받고 전송성공 시그널을 응답할때까지 지연이 발생합니다. 이 때문에 지속적으로 카카오톡 전송결과를 확인해야 하는 불편함 대신에, 지정한 콜백 URL으로 실시간 전송되는 HTTP 메시지를 활용하여 쉽고 편하게 카카오톡 전송 결과를 확인할 수 있습니다..

커넥트 서비스 프로세스

1) 커넥트 이벤트 발생 : 팝빌은 파트너의 콜백 URL를 확인합니다.

2) HTTP Request : 파트너의 해당 콜백 URL로 HTTP POST Request 메시지를 보냅니다.

3) Request 정보 확인 : 파트너는 HTTP POST Request의 Body에 담긴 JSON 객체 형태의 값을 확인하고 처리합니다.

4) HTTP Response

파트너의 정보 처리가 성공이라면, OK(String) 또는 {"result" : "OK"}(JSON Object) 값을 HTTP Response로 보냅니다. 이 때 HTTP 통신 오류(Read timeout, Gateway timeout, SSL 오류 등)로 인해 커넥트 실패시 5분 간격으로 총 3회 재시도됩니다.

5) Response 결과 확인

팝빌은 Response 결과 값에 따라 커넥트 성공/실패를 판별하며, 실패 건에 대해 모니터링하여 고객사 서버의 장애 감지시 유선으로 안내해 드립니다.

커넥트 프로세스 흐름도

커넥트 유형 및 설정 방법

팝빌에서는 두가지 커넥트 방식을 지원하며 유형에 따른 설정 방법은 하단의 표를 참고하시기 바랍니다.

구분 통합 설정 개별 설정
적용 대상 고객사의 모든 회원 하나의 회원
설정 방법 팝빌에서 일괄 적용
> 이용할 콜백 URL을 메일(code@linkhub.co.kr)로 전송
1. 팝빌에 커넥트 서비스 사용 요청
2. 팝빌 사이트 접속
3. [ 문자 · 팩스 > 커넥트 관리 > 커넥트 등록 ] 접속
4. 커넥트 유형 REST 설정
5. 콜백 URL에 사용할 주소 입력
6. 커넥트 인증 미사용 설정

※ 커넥트 서비스는 80 / 443 / 9854 포트를 이용 할 수 있으며, 다른 포트 이용이 필요한 경우 기술지원센터(1600-9854)로 문의주시기 바랍니다.

커넥트 수신 예제코드 - .NET

1) 커넥트 수신 기능을 구현하기 위한 Web API 프로젝트를 생성합니다.

C#.NET Webhook Connect

2) JSON 포맷의 커넥트 메시지를 매핑하기 위한 프로젝트 Models/ 폴더에 모델 클래스 파일을 추가합니다.

ㆍ추가적인 커넥트 필드 항목은 [커넥트 이벤트 메시지 구성]을 참조하여 추가합니다.

C#.NET Webhook Connect Model
using System;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;

namespace WebApplication1.Models
{
    public class PopbillConnect
    {
        public string eventDT { get; set; }
        public string eventType { get; set; }
        // 하단의 [커넥트 이벤트 메시지 구성]을 참조하여 모델 필드 추가
    }
}

3) POST 메시지를 처리하는 C# APIController 코드를 추가합니다.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using WebApplication1.Models;

namespace WebApplication1.Controllers
{
    public class ValuesController : ApiController
    {

        // POST api/values
        public HttpResponseMessage Post([FromBody]PopbillConnect jsonInfo)
        {
            var response = new HttpResponseMessage();
            response.Headers.Add("ContentType", "text/plain");

            // PopbillConnect 모델에 선언된 필드 매핑
            String eventDT = jsonInfo.eventDT;
            String eventType = jsonInfo.eventType;

            Console.WriteLine(eventType);

            // 커넥트 성공 응답 처리
            response.StatusCode = HttpStatusCode.OK;
            response.Content = new StringContent("OK");

            return response;
        }
    }
}

4) 서버 주소를 팝빌 커넥트 콜백 URL에 등록하고 커넥트 메시지 수신을 테스트합니다.

팝빌 카카오톡 커넥트 메시지 구성

1) 커넥트 메시지 Header 구성
항목명 설명 예시
Accept 팝빌이 원하는 미디어타입 text/plain, */*
User-Agent 요청을 보낸 서버 정보 Popbill webhook executor (KAKAO.STATE)
Pb-Webhook-Type 커넥트 서비스 유형 KAKAO.STATE
Pb-Webhook-MID 이벤트 식별값 016120000002-1777d55c2c41492ab06826d
Pb-Webhook-Corpnum 팝빌 사업자번호 6798700433
Content-Type 커넥트 메시지의 Body 타입 application/json
Host 요청 대상이 되는 호스트 정보 docs.popbill.com
Connection 팝빌과 고객사 간에 커넥트 연결 옵션 keep-alive
Content-Length 커넥트 메시지의 Body 길이 243
Authorization 커텍트 인증 - BASIC 이용시
Requset Header에 추가되는 항목
Basic VEVTVDoxMjM=
X-Api-Key 커넥트 인증 - API KEY 이용시
Requset Header에 추가되는 항목
TEST
2) 커넥트 메시지 Body 구성
항목명 설명 타입 길이 비고
serialNum 일련번호 Number -
receiptNum 접수번호 String 18
requestNum 전송요청번호 String 36
receiptDT 접수일시 String 14 형식 : yyyyMMddHHmmss
state 알림톡/친구톡
전송상태 코드
Number 1 0 : (접수) / 1 : (대기중) / 2 : (처리중) /
3 : (완료) / 4 : (취소) 중 반환
※ 전송상태 코드 상태 값은 작아지지 않음
└ 예) 3 => 2 변경 X
result 알림톡/친구톡
전송결과 코드
Number 3 상태코드가 3 인 경우, result 값이 존재[참고] 전송 상태 및 결과 코드
resultDT 알림톡/친구톡
전송결과 수신일시
String 14 형식 : yyyyMMddHHmmss
sendDT 알림톡/친구톡 전송일시 String 14 형식 : yyyyMMddHHmmss
altResult 대체문자 전송결과 코드 Number 3 [참고] 전송 상태 및 결과 코드
altResultDT 대체문자 전송결과 수신일시 String 14 형식 : yyyyMMddHHmmss
altSendDT 대체문자 전송일시 String 14 형식 : yyyyMMddHHmmss
corpNum 팝빌회원 사업자번호 String 10
receiveNum 수신번호 String 20
sendNum 발신번호 String 20
contentType 카카오톡 전송유형 Number 1 1 : (알림톡) / 2 : (친구톡 텍스트) /
3 : (친구톡 이미지) 중 반환
eventType 이벤트 유형 String - "RESULT" / "MANUAL" 중 반환
└ RESULT = 팝빌 시스템에서 카카오톡 전송 결과 확인하여 자동으로 커넥트 실행한 경우
└ MANUAL = 팝빌 사이트에서 사용자가 수동으로 커넥트 실행한 경우
eventDT 이벤트 실행일시 String 14 형식 : yyyyMMddHHmmss
interOPRefKey 파트너 지정 키 String 20 대량/동보전송시 파트너가 개별건마다 입력한 값

커넥트 이벤트 메시지 Request Body 예시

이벤트 형식 HTTP Request Body 설명
카카오톡
전송 결과
{
"serialNum": 1,
"receiptNum": "020111219005200001",
"altSendDT": "20201112190059",
"receiptDT": "20201112190052",
"altResultDT": "20201112190059",
"interOPRefKey": "20201112-A001"
"eventType": "RESULT",
"result": 622,
"corpNum": "1234567890",
"resultDT": "20201112190056",
"altResult": 100,
"sendDT": "20201112190054",
"receiveNum": "01043245117",
"state": 3,
"sendNum": "07043042991",
"contentType": 1,
"eventDT": "20201112190059"
}

- 이벤트 유형(eventType)에 "RESULT" 반환
- 카카오톡 전송 상태(state)를 통해 확인
- 카카오톡 전송 유형(contentType) 및 결과 코드(result)를 통해 확인
- 대체문자 전송 결과 코드(altResult)를 통해 확인
- 대체문자 전송을 하지 않을 경우 alt* 값들은 전송하지 않음

※ 카카오톡 전송상태 코드(state) 값을 UPDATE 하는 경우, 전송상태값은 작아지지 않음을 유의하셔야 합니다.

커넥트 응답 메시지(처리 결과 메시지) 구성

커넥트 이벤트 실행에 대해 수신 성공 처리를 위해서는 응답 메시지 Body 를 아래와 같이 두가지 응답 타입 중 한가지를 반환하도록 처리하면 됩니다.

유형 String 타입 JSON 타입
Body 메시지 "OK" {
"result":"OK"
}

기술지원센터

팝빌 기술지원은 유선, 메일, 원격지원 등 다양한 채널을 통해 제공됩니다.

T. 1600-9854 E. code@linkhub.co.kr

연동문의