> ## Documentation Index
> Fetch the complete documentation index at: https://developer.alltalk.co.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS 발송

> 등록된 발신번호를 통해 단문 메시지(SMS)를 전송합니다.

<Warning>
  * **메시지 길이 제한**: SMS는 최대 **90바이트** (한글 약 45자). 초과 시 자동으로 잘리거나 발송 실패할 수 있습니다. 장문이 필요하면 [LMS](/api-reference/messaging/lms)를 사용하세요.
  * **발신번호 사전 등록**: `callbackNo` 에 사용할 발신번호는 반드시 사전에 등록되어 있어야 합니다. 미등록 번호 사용 시 발송이 거부됩니다.
</Warning>

## Headers

<ParamField header="apikey" type="string" required>
  제공받은 API key
</ParamField>

<ParamField header="groupId" type="string" required>
  그룹 코드
</ParamField>

## Body (JSON)

<ParamField body="service" type="number" required>
  제공받은 SMS 서비스 번호
</ParamField>

<ParamField body="message" type="string" required>
  발송할 메시지 (최대 90바이트)
</ParamField>

<ParamField body="numbers" type="string[]" required>
  수신자 핸드폰 번호 배열. 예: `["01012345678", "01087654321"]`
</ParamField>

<ParamField body="groupId" type="string" required>
  그룹코드
</ParamField>

<ParamField body="callbackNo" type="string" required>
  발신번호. 사전에 등록되어있는 발신번호만 사용 가능합니다.
</ParamField>

<ParamField body="mapping" type="object[]">
  가변 변수 매핑 배열. `numbers` 와 동일 순서로 매칭됩니다.
  각 항목은 템플릿의 `#{name}`, `#{VAR1}` 등에 대입될 값을 담습니다.
</ParamField>

## 예제

<RequestExample>
  ```javascript Node.js theme={null}
  const smsData = {
    service: 1234567890,
    message: '#{name}님, 인증번호는 #{VAR1}입니다.',
    numbers: ['01012345678', '01087654321'],
    groupId: 'YOUR_GROUP_ID',
    callbackNo: '16612460',
    mapping: [
      { name: '홍길동', VAR1: '123456' },
      { name: '김철수', VAR1: '654321' },
    ],
  };

  await axios.post('https://api.alltalk.co.kr/sms', smsData, {
    headers: {
      apikey: 'YOUR_API_KEY',
      groupId: 'YOUR_GROUP_ID',
    },
  }).then((res) => {
    console.log('전송 결과:', res.data);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "success",
    "code": "200",
    "datetime": "2024-01-15 14:30:25",
    "value": [
      {
        "uid": 37668015179,
        "date": 1705297825053,
        "status": "SMS_00"
      },
      {
        "uid": 37668015180,
        "date": 1705297825055,
        "status": "SMS_00"
      }
    ],
    "count": 2,
    "total": 2
  }
  ```
</ResponseExample>

## 응답 필드

| 필드                | 설명                                                            |
| ----------------- | ------------------------------------------------------------- |
| `status`          | `success` / `fail`                                            |
| `code`            | HTTP 상태 코드                                                    |
| `datetime`        | 응답 시각                                                         |
| `value[].uid`     | 수신자별 발송 식별자                                                   |
| `value[].date`    | 발송 시각 (epoch ms)                                              |
| `value[].status`  | 수신자별 결과 코드. `SMS_00` = 진행 중 ([에러 코드](/guides/error-codes) 참조) |
| `count` / `total` | 처리된 건수 / 전체 요청 건수                                             |

<Note>
  `status` 값은 **발송 접수 상태**를 나타냅니다. 실제 수신자에게 도달했는지는
  별도의 결과 조회 또는 콜백을 통해 확인하세요.
  결과 조회가 필요하신 경우 영업 담당자에게 문의하시기 바랍니다.
</Note>