メインコンテンツまでスキップ

SMS/RCS / クイックリファレンス

最初に押さえておく共通仕様をまとめます。各エンドポイントの詳細は API リファレンス を参照してください。

ベース URL​

環境ベース URL
本番https://api.mico.one/

契約情報から取得する値​

API の呼び出しに必要な値は、契約の時点でお渡しした認証情報を参照してください。

値指定先用途
クライアント IDPOST /oauth/token の client_idアクセストークンの取得
クライアントシークレットPOST /oauth/token の client_secret同上
サイト UUIDX-SITE-UUID ヘッダ配信元サイトの指定。SMS 配信 API のすべてのコールで必須
送信元電話番号配信予約・即時配信の sender_phone_number送信元として指定。エンドユーザーの端末に表示される番号

送信元電話番号は 公式アカウント開設申請書 に記載されています（Mico SMS/RCS サービス申込書 には含まれません）。事前に登録された番号のみ使用できます。

認証​

SMS 配信 API（/engage/v1/sms_delivery/**）のすべてのコールに、アクセストークン (JWT) と サイト UUID の 2 つが必要です。下記の「エンドポイント一覧」で認証が「必要」の 7 つが対象です。

Authorization: Bearer <access_token>
X-SITE-UUID: <site_uuid>

どちらかを省略すると 401 Unauthorized になります。トークンは POST /oauth/token で取得します（grant_type は client_credentials のみ）。

次の 2 つは SMS 配信 API ではないため、トークンもサイト UUID も不要です。

  • GET /health
  • POST /oauth/token

エンドポイント一覧​

用途エンドポイント認証
ヘルスチェックGET /health不要
トークン生成POST /oauth/token不要
配信リストアップロードPOST /engage/v1/sms_delivery/delivery_list必要
アップロード状況の確認GET /engage/v1/sms_delivery/delivery_list?upload_id=必要
配信予約POST /engage/v1/sms_delivery/schedules必要
即時配信POST /engage/v1/sms_delivery/send必要
配信キャンセルPOST /engage/v1/sms_delivery/{delivery_request_id}/cancel必要
配信サマリーGET /engage/v1/sms_delivery/{delivery_request_id}必要
配信レポート（宛先ごと）POST /engage/v1/sms_delivery/{delivery_request_id}/recipients必要

利用シナリオと配信の流れ​

API は受け付けたことしか返しません。 CSV の取り込みも実際の送信も、API の裏側にある配信システムが非同期に進めます。図の「配信システム」との往復は、クライアントからは直接見えない処理です。結果はポーリング（サマリー / レポートの取得）で確認します。

シナリオ 1: 通常の予約配信​

指定した日時に配信するための機能です。

  1. トークンを取得する（POST /oauth/token）
  2. 顧客リストの CSV をアップロードする（POST /engage/v1/sms_delivery/delivery_list）
  3. アップロードの完了を確認する（GET /engage/v1/sms_delivery/delivery_list）
  4. 配信をスケジュールする（POST /engage/v1/sms_delivery/schedules）— 例: 18:00 に送信
  5. スケジュールした時刻に自動で配信される
  6. 必要に応じて進行状況を確認する（GET /engage/v1/sms_delivery/{delivery_request_id}）
  7. 完了後、宛先ごとの結果を取得する（POST /engage/v1/sms_delivery/{delivery_request_id}/recipients）

手順 3 は省略できません。アップロードは非同期処理のため、status が COMPLETED になって delivery_list_id が払い出されるまで手順 4 に進めません。

シナリオ 2: 予約配信のキャンセル​

予約した配信を取り消す経路です。手順 1〜4 はシナリオ 1 と同じです。

  1. トークンを取得する
  2. CSV をアップロードする
  3. アップロードの完了を確認する（status が COMPLETED になるまで）
  4. 配信をスケジュールする
  5. 配信開始前にキャンセルする（POST /engage/v1/sms_delivery/{delivery_request_id}/cancel）
  6. ステータスが CANCELLED になったことを確認する

配信が既に開始している、完了している、もしくは既にキャンセル済みの場合はキャンセルできず、412 が返ります。

シナリオ 3: 少数宛先に即時配信​

少数の宛先へ送る経路です。CSV のアップロードは不要です。

  1. 宛先と差し込み値を指定して即時配信する（POST /engage/v1/sms_delivery/send）— 最大 10 件
  2. 必要に応じて進行状況を確認する（GET /engage/v1/sms_delivery/{delivery_request_id}）
  3. 完了後、宛先ごとの結果を取得する（POST /engage/v1/sms_delivery/{delivery_request_id}/recipients）

即時配信は受け付けた時点で配信が始まるため、キャンセルできません。

配信リクエストのステータス遷移​

即時配信は PROCESSING から始まり、キャンセルできません。予約配信も、配信が始まった後（PROCESSING）はキャンセルできません。

配信結果の件数​

配信サマリー（GET /engage/v1/sms_delivery/{delivery_request_id}）が返す件数の意味です。

フィールド意味
target_count配信対象となった全宛先の総数
success_count配信に成功した宛先の総数
failure_count配信に失敗した宛先の総数
skipped_count配信を試みなかった総数

target_count = success_count + failure_count + skipped_count は、配信が完了して初めて成立する式です。配信中はまだ結果が確定していない宛先が残るため、target_count が成功・失敗・スキップ数の合計よりも大きくなります。status が PENDING のうちは target_count も 0 です。

配信されなかった宛先の確認​

配信できないと判断された宛先は、判断された時点によって確認できる場所が変わります。

時点確認できる場所API
配信リストの登録時validation_failed_count（件数のみ。どの番号かは分かりません）アップロード状況の確認
配信時宛先ごとのステータスに INVALID として出ます配信レポート

登録時に弾かれた宛先は配信レポートに現れません。 件数だけが validation_failed_count で分かります。

skipped_count は INVALID の件数と一致するとは限りません。配信を試みなかった宛先をまとめて数えているため、上記の両方に加えて、配信可否の判定でスキップされた宛先も含みます。

電話番号の形式​

配信リスト CSV では phone_number と country_dial_code の 2 カラムが必須です（カラム位置は任意ですが先頭 2 つを推奨）。3 カラム目以降は、メッセージ本文の変数として使えます。

例の電話番号はプレースホルダです

本ドキュメントに出てくる電話番号の X は任意の数字 1 桁を表すプレースホルダです。実際には半角数字を指定してください。X を含んだままでは送信できません。

即時配信（POST /engage/v1/sms_delivery/send）はキャンセルできないため、動作確認は必ず自社で管理している番号に対して行ってください。

次の表の X も同じプレースホルダです。可否は X を半角数字に置き換えた場合の判定を示します。

phone_numbercountry_dial_code可否備考
090XXXXXXX1+81○国内形式は国番号の指定が必須
+8190XXXXXXX3（空）○国際電話番号形式 (E.164) なら国番号は省略可
090-XXXX-XXX4+81○ハイフン・スペース・丸括弧は可
080 (XXXX) XXX6+81○同上
０９０１２３４５+81×全角文字は使用不可
  • 現時点で対応するのは日本向け（+81）のみです
  • 同一ファイル内で形式が混在していても構いません
  • 配信レポートでは、入力した表記がそのまま返ります（正規化されません）

URL 短縮​

本文中の URL を短縮 URL に置き換えられます。即時配信 でのみ指定できます（配信予約にはこの設定がありません）。

url_shortening_strategy と boundary_strategy の値・検知の具体例・注意事項は Mico の配信システムの共通仕様です。共通仕様 / 短縮 URL を参照してください。

エラーレスポンス​

エラーは共通の形で返ります。trace_id は問い合わせの際に伝えてください。

{
  "code": 400,
  "message": "some fields failed validation",
  "details": {
    "trace_id": "9b7d4c1e-3f2a-4b8c-9d6e-1a2b3c4d5e6f",
    "field_violations": [
      {
        "code": "REQUIRED",
        "field": "message",
        "description": "is required",
        "parameters": {}
      }
    ]
  }
}
ステータス主な原因
400必須フィールド不足・型不正・形式不正・列挙値外・範囲外
401トークンまたは X-SITE-UUID が不正・不足。POST /oauth/token では client_id / client_secret が不正
404指定した upload_id / delivery_list_id / delivery_request_id が無い
409idempotency_key が既に使われている。配信予約（POST .../schedules）と即時配信（POST .../send）で返ります
412配信が既に開始・完了・キャンセル済みでキャンセルできない