# 문자 발송 API

## 사전 작업 <a href="#pre-work" id="pre-work"></a>

### 토큰 발급 <a href="#token" id="token"></a>

서버에서 발송API를 요청하기 전, 먼저 프로젝트에 유효한 토큰을 발급받아 주세요.

{% content-ref url="../authentication" %}
[authentication](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/open-api/authentication)
{% endcontent-ref %}

### 채널 설정 <a href="#channel" id="channel"></a>

* 메시지 발송을 위해서는 발신번호를 사전 등록해야 합니다
* 콘솔 경로 :&#x20;
  * 발신 프로필 등록 : \[마켓탭 콘솔 > 채널 관리 > 문자 메시지 설정 ]

    <figure><img src="https://content.gitbook.com/content/TQoY0rYrzNUQxhlUfYFm/blobs/Z5WPy9q4trrLUxswDafK/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-03-31%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.52.31.png" alt="" width="563"><figcaption></figcaption></figure>

## 문자 메시지 발송 API <a href="#api" id="api"></a>

**Method**: `POST`

**Content-Type**: `application/json`

```json
[
  {
    "sender_profile_id": "g75znkc",
    "campaign_id": "test_campaign_id",
    "sub_channel_type": "LMS",
    "user_id": "user_124",
    "phone_number": "01000000000",
    "message": {
      "title": "회원가입",
      "content": "안녕하세요, 고객님!\n회원가입 진심으로 축하드립니다.\n\n{{vcq2hgl9}}",
      "opt_out_message": "(무료거부: 수신거부 080-000-0000)"
    },
    "tracking_options": [
      {
        "id": "vcq2hgl9",
        "redirectUrl": "https://naver.com/"
      }
    ],
    "is_ad_message": true
  },
  {
    "sender_profile_id": "g75znkc",
    "campaign_id": "test_campaign_id",
    "sub_channel_type": "MMS",
    "user_id": "user_124",
    "phone_number": "01000000000",
    "message": {
      "title": "회원가입",
      "content": "안녕하세요, 고객님!\n회원가입 진심으로 축하드립니다.",
      "image_url": "https://mud-kage.kakao.com/dn/45Tx8/btsNSHSFCtG/z2kEOEkGdoV6POAUQdPQsd/img_l.jpg"
    },
    "tracking_options": [],
    "is_ad_message": false
  }
]
```

### Payload 필드 설명

<table><thead><tr><th width="196.80645751953125">필드명</th><th width="482.5242919921875">설명</th><th>필수 여부</th></tr></thead><tbody><tr><td><code>sender_profile_id</code></td><td>문자 메시지 발신 프로필 ID</td><td><mark style="color:red;">required</mark></td></tr><tr><td><code>sub_channel_type</code></td><td><p>문자 메시지 하위 채널 타입 ( SMS, LMS, MMS )</p><p>메시지 하위 채널 타입은 실제 발송할 메시지의 <strong>내용 및 길이</strong>에 따라 자동으로 변경될 수 있습니다.<br></p><ul><li>기본적으로 SMS 타입으로 설정하여 발송하더라도, <code>message.content</code>의 길이가 <strong>90 byte를 초과</strong>하는 경우 자동으로 <strong>LMS 타입</strong>으로 변경되어 발송됩니다.</li><li>메시지에 <strong>제목</strong>을 입력한 경우에는 <strong>메시지 길이에 관계없이</strong> LMS 타입으로 발송되며, 최대 <strong>2000byte</strong>까지 지원됩니다.</li><li>메시지에 이미지를 입력한 경우는 MMS 타입으로 발송됩니다.</li></ul></td><td></td></tr><tr><td><code>campaign_id</code></td><td>메세지 발송 결과를 캠페인 ID 단위로 확인하고 싶을때 사용하실수 있습니다.</td><td></td></tr><tr><td><code>user_id</code></td><td>메세지 발송 결과를 확인할 유저 ID</td><td><mark style="color:red;">required</mark></td></tr><tr><td><code>phone_number</code></td><td>발송 대상 전화 번호 ( ex <code>01012345678</code> )</td><td><mark style="color:red;">required</mark></td></tr><tr><td><code>message</code></td><td><p>실제 발송할 메시지 내용 </p><p></p><ul><li>title: 문자 메시지 제목</li><li>content: 문자 메시지 본문</li><li>image_url: 문자 메시지 이미지 URL<br><a href="broken-reference">문자 메시지 이미지 업로드 API</a>를 통해 이미지를 업로드한 후 반환된 URL을 입력해주세요.</li><li>opt_out_message: 수신거부 문구</li></ul></td><td><mark style="color:red;">required</mark></td></tr><tr><td><code>tracking_options</code></td><td>추적 URL 옵션.<br>해당 옵션을 추가하는 경우 url 랜딩을 추적해서 성과를 측정할 수 있습니다.<br><br>메시지 본문(<code>content</code>)에서 단축 URL로 설정 할 부분을 <code>{{ 랜덤 문자열 }}</code> 형식으로 지정합니다.<br>이후,<code>tracking_options</code>에 해당 랜덤 문자열과 매핑 될 실제 URL을 추가합니다.</td><td></td></tr><tr><td><code>is_ad_message</code></td><td><p>광고성 메시지 여부. true 일 경우 광고성 메시지, false 일 경우 정보성 메시지로 판단합니다. 기본값은 false 입니다.</p><p></p><ul><li><p>true (광고성 메시지인 경우)</p><ul><li>광고성 야간 발송 정책이 적용됩니다 (오후 8시 30분 ~ 오전 8시 발송 제한).</li><li>본문 맨 앞 <code>(광고)</code> 문구가 자동 삽입됩니다.</li><li><code>message.opt_out_message</code> (수신거부 문구) 필드 값이 본문 하단에 삽입되고, null 인 경우 삽입하지 않습니다.</li></ul></li><li><p>false (정보성 메시지인 경우)</p><ul><li>본문 앞 <code>(광고)</code> 문구가 삽입되지 않습니다.</li><li><code>message.opt_out_message</code> (수신거부 문구) 필드 값이 존재하더라도 삽입되지 않습니다.</li></ul></li></ul></td><td></td></tr></tbody></table>

### 주의사항 및 기타 안내 <a href="#notifications" id="notifications"></a>

* 발송 API는 실시간으로 처리되며, 요청당 최대 100개의 전화번호로 발송이 가능합니다.
* 수신 번호가 유효하지 않거나 템플릿이 승인되지 않은 경우 실패 응답이 반환됩니다.
* 묶음 발송인 경우 **병렬처리가 아닌 순차적 발송**으로 단건 발송에 비해 응답 속도가 느릴수 있는점 참고 부탁드립니다.
* 트래픽 집중 시간대에는 발송이 지연될 수 있습니다.

## Open API 스펙

## Send a text message

> Sends a simple text message to a specified phone number.

```json
{"openapi":"3.0.0","info":{"title":"Marketap Message API","version":"1.0.0"},"servers":[{"url":"https://crm.marketap.io","description":"Production Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SendTextMessageReq":{"type":"object","required":["phone_number","sender_profile_id","message","user_id"],"properties":{"phone_number":{"type":"string"},"sub_channel_type":{"type":"string","enum":["SMS","LMS","MMS"]},"sender_profile_id":{"type":"string"},"campaign_id":{"type":"string"},"user_id":{"type":"string"},"message":{"type":"object","properties":{"content":{"type":"string"},"title":{"type":"string"},"image_url":{"type":"string","format":"uri"},"opt_out_message":{"type":"string","description":"수신거부 문구. is_ad_message가 true일 때 본문 뒤에 추가됩니다."}},"required":["content"]},"is_ad_message":{"type":"boolean","default":false,"description":"광고 메시지 여부. true인 경우 본문 앞에 (광고)가 추가되고, 야간 시간대(20:50~08:00) 발송이 제한됩니다."},"tracking_options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"redirect_url":{"type":"string","format":"uri"}}}}}},"SenderResponse":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SendMessageResult"}}}},"SendMessageResult":{"type":"object","properties":{"message_id":{"type":"string"},"user_id":{"type":"string"},"phone_number":{"type":"string"},"status":{"type":"integer"},"message":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},"paths":{"/api/v1/sender/text-message":{"post":{"summary":"Send a text message","description":"Sends a simple text message to a specified phone number.","parameters":[{"name":"project_id","in":"query","required":true,"schema":{"type":"string"},"description":"프로젝트 ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SendTextMessageReq"}}}}},"responses":{"200":{"description":"The request has been accepted for processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SenderResponse"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```