개요

본 문서는 (주)유라클에서 제공하는 “message.AI”의 연동 API 정의서를 설명하고 있다. 본 문서는 성능 개선, 기능 추가 등의 사항으로 내용이 변경될 수 있다.

목적

본 문서는 UMS 서비스의 연동을 위한 제반 사항을 기술한다.

호출 방법

Receiver Server 에 HTTP (POST) 방식으로 연동 API URL 을 호출 하면 JSON Format으로 결과를 반환.

예) http://[Receiver IP]:[Receiver Port]/[API PATH]

한글깨질경우 Content-Type에 charset=UTF-8 설정.

TLS Protocol은 TLSv1.2 이상 만 지원.

API키 생성 방법

API 호출방식을 사용하기 위해서는 API키를 발급 받아야 한다.

Step1. message.AI(https://www.message-ai.net)에 회원가입을 합니다.

Step2. 로그인 하신 후 서비스그룹으로 이동한다.

Step3. 서비스그룹 추가 후 요금제 선택/이용 상품을 선택한후 결제를 한다.

Step4. 생성된 서비스그룹의 API Key관리에서 API키를 생성한다.

참조 : 홈페이지 사용자 가이드에서 확인 하기

실패 처리 방법

① 인증키 시간만료 (인증키 요청 API 호출)

HTTP Error code = HTTP/1.1 200 OK

JSON Data parsing

HEADER - RESULT_CODE = 0000

BODY ? AUTHKEY 값 저장 및 이후 서버로 호출 시 항상 파라미터로 사용

전문 구성

UMS API 전문은 공통 전문 + 채널 전문으로 구성된다. 대체 발송을 위해 SEND_MACRO_CODE 값 입력 시 아래와 같이 발송 전문을 작성하여야 한다.

예1) PUSH: 공통 전문 + PUSH 전문

예2) SMS: 공통 전문 + SMS 전문

예3) PUSH > SMS 전환 발송: 공통 전문 + PUSH 전문 + SMS 전문

예4) PUSH > RCS > SMS 전환 발송 : 공통 전문 + PUSH 전문 + RCS 전문 + SMS 전문

필수 라이브러리

  <!-- MAVEN 필수 라이브러리 -->

  <dependencies>
    <!-- Apache HttpClient dependency -->
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.13</version>
    </dependency>

    <!-- Apache HttpMime dependency for multipart support -->
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpmime</artifactId>
        <version>4.5.13</version>
    </dependency>

    <!-- Additional dependencies if needed -->
</dependencies>

샘플

주의

chatGPT4.0 가입고객은 GPTs를 통해 샘플코드를 작성을 할 수 있습니다. - Chat GPT 바로가기

UMS 발송예제 JDK 1.8 이상

  package com.uracle.extention.test;

  import org.apache.http.client.methods.CloseableHttpResponse;
  import org.apache.http.client.methods.HttpPost;
  import org.apache.http.entity.mime.MultipartEntityBuilder;
  import org.apache.http.impl.client.CloseableHttpClient;
  import org.apache.http.impl.client.HttpClients;
  import org.apache.http.util.EntityUtils;

  import java.io.IOException;

  public class PushMessageSender {

     public static void main(String[] args) {

        String apiUrl = "https://api.message-ai.net/api/send/potalSendApi.ums";

        //발송 대상 서비스그룹에서 생성한 API Key를 입력하세요.
        String apiKey = "YOUR_API_KEY";
        //발송 대상 서비스그룹의 서비스그룹ID를 입력하세요.
        String projectId = "YOUR_PROJECT_ID";
        //발송자는 서버관리를 위한 회원님 고유의 아이디를 입력하세요.
        String senderId = "YOUR_SENDER_ID";
        //발송 대상 서비스그룹의 서비스그룹ID를 입력하세요.
        String appId = "YOUR_APP_ID";
        //푸시 발송 제목을 입력하세요.
        String messageTitle = "제목";
        //푸시 발송 내용을 입력하세요.
        String messageContent = "안녕하세요. 푸시 메시지를 보냅니다.";

        String cuids ="{\"user1\":[\"0100000000\",\"홍길동\"],\"user2\":[\"0100000000\",\"김철수\"]}";

        try (CloseableHttpClient httpClient = HttpClients.createDefault()) {

              HttpPost postRequest = new HttpPost(apiUrl);

              // multipart/form-data를 사용하여 요청 엔티티를 생성합니다.
              MultipartEntityBuilder builder = MultipartEntityBuilder.create();
              builder.addTextBody("APIKEY", apiKey);
              builder.addTextBody("PROJECT_ID", projectId);
              builder.addTextBody("REQ_TRAN_TYPE", "REAL");  // 실시간 전송
              builder.addTextBody("TARGET_USER_TYPE", "NM");  // 일반 발송
              builder.addTextBody("SENDERID", senderId);
              builder.addTextBody("APP_ID", appId);
              builder.addTextBody("TITLE", messageTitle, ContentType.MULTIPART_FORM_DATA.withCharset("UTF-8"));
              builder.addTextBody("PUSH_MSG", messageContent, ContentType.MULTIPART_FORM_DATA.withCharset("UTF-8"));
              builder.addTextBody("CUIDS", cuids);

              postRequest.setEntity(builder.build());

              try (CloseableHttpResponse response = httpClient.execute(postRequest)) {
                 String responseBody = EntityUtils.toString(response.getEntity());
                 System.out.println("Response: " + responseBody);
              }
        } catch (IOException e) {
              e.printStackTrace();
        }
     }
}

UMS 발송예제 JDK 1.7 이하

package com.uracle.extention.test;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.KeyStore;
import java.util.HashMap;
import java.util.Map.Entry;

import javax.net.ssl.HttpsURLConnection;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManager;
import javax.net.ssl.TrustManagerFactory;

import java.io.IOException;

public class PushMessageSender {

   public static void main(String[] args) throws IOException {

      BufferedReader in = null;
      String apiUrl = "https://api.message-ai.net/api/send/potalSendApi.ums";

      //발송 대상 서비스그룹에서 생성한 API Key를 입력하세요.
      String apiKey = "YOUR_API_KEY";
      //발송 대상 서비스그룹의 서비스그룹ID를 입력하세요.
      String projectId = "YOUR_PROJECT_ID";
      //발송자는 서버관리를 위한 회원님 고유의 아이디를 입력하세요.
      String senderId = "YOUR_SENDER_ID";
      //발송 대상 서비스그룹의 서비스그룹ID를 입력하세요.
      String appId = "YOUR_APP_ID";
      //푸시 발송 제목을 입력하세요.
      String messageTitle = "제목";
      //푸시 발송 내용을 입력하세요.
      String messageContent = "안녕하세요. 푸시 메시지를 보냅니다.";

      String cuids ="{\"user1\":[\"0100000000\",\"홍길동\"],\"user2\":[\"0100000000\",\"김철수\"]}";

      try {
         SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
         TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
         trustManagerFactory.init((KeyStore) null);
         sslContext.init(null, (TrustManager[]) trustManagerFactory.getTrustManagers(), null);
         javax.net.ssl.SSLSocketFactory sslSocketFactory = sslContext.getSocketFactory();

         HashMap<String, Object> params = new HashMap<String, Object>();

         params.put("APIKEY", apiKey);
         params.put("PROJECT_ID", projectId);
         params.put("REQ_TRAN_TYPE", "REAL");
         params.put("TARGET_USER_TYPE", "NM");
         params.put("SENDERID", senderId);
         params.put("APP_ID", appId);
         params.put("TITLE", messageTitle);
         params.put("PUSH_MSG", messageContent);
         params.put("CUIDS", cuids);
         StringBuilder postData = new StringBuilder();
         for(Entry<String, Object> param : params.entrySet())
         {
            if(postData.length() != 0)
               postData.append('&');
            postData.append(param.getKey());
            postData.append('=');
            postData.append(String.valueOf(param.getValue()));
         }


         System.out.println("Send Data " + postData.toString());

         byte[] postDataBytes = postData.toString().getBytes();

         URL obj = new URL(apiUrl); // 호출할 URL
         HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
         con.setSSLSocketFactory(sslSocketFactory);
         con.setRequestMethod("POST");
         con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
         con.setDoOutput(true);
         con.getOutputStream().write(postDataBytes); // POST 호출

         in = new BufferedReader(new InputStreamReader(con.getInputStream(), StandardCharsets.UTF_8));
         String line;
         while ((line = in.readLine()) != null) {
            System.out.println(line);
         }
      } catch (Exception e) {
         e.printStackTrace();
      } finally {
         if (in != null) {
            try {
               in.close();
            } catch (Exception e) {
               e.printStackTrace();
            }
         }
      }
   }
}