SMS API

Contact Center AI Platform（CCAI プラットフォーム）では、SMS API を使用して、インバウンドとアウトバウンドの SMS メッセージを処理できます。

認証

SMS API を使用するには、認証情報が必要です。

SMS API の認証情報を作成する手順は次のとおりです。

  1. CCAI Platform ポータルで、[設定] > [デベロッパー設定] > [API 認証情報の管理] をクリックします。

  2. [+ API 認証情報を追加] ボタンをクリックします。[API 認証情報を追加] メッセージが開きます。

  3. 認証情報の名前を入力します。

  4. [作成] をクリックします。

Outbound SMS API

アウトバウンド SMS API は、アウトバウンド SMS メッセージを開始するためのエンドポイントを提供します。これにより、プログラムで SMS メッセージをユーザーに送信できます。

この API を使用する際は、次の 3 つの重要な点に注意してください。

  • このサービスは、一度に数万件のメッセージを送信するように設計されていません。目標はイベント駆動型メッセージングです。

  • お客様は SMS メッセージに返信して、サポート セッションを開始できます。

  • この API は、同じ日に同じ番号に複数の SMS メッセージを送信する必要がある場合には機能しません。

ユースケース

アウトバウンド SMS API のユースケースの例はイベント ベースです。たとえば、注文の受け取り準備ができたことを消費者に通知し、返信のオプションも提供する場合などです。アウトバウンド SMS が送信されると、アクティブなセッションが作成されます。お客様が返信すると、エージェントに転送されます。

この API と Sessionless Outbound SMS API の違いは、セッションレスでは通知のみを送信し、消費者が返信した場合、デフォルトのメッセージ（設定されている場合）が送信され、エージェントに転送されないことです。

その他のユースケース:

  • アカウントへのログイン。
  • アカウント アクティビティ。
  • アカウントの使用状況に関する重要なイベント。
  • 接続されているデバイスの問題の検出。
  • 配達やライドシェアなどのオンデマンド サービスに関する到着予定時刻の通知。
  • 予約のリマインダー。
  • サービスやアカウントに関する事前通知。
  • 2 段階認証（お客様が既存のコード生成ツールとサービス プロセスをお持ちの場合）。

アウトバウンド SMS API エンドポイント

この新しいエンドポイントのベース URI は次のとおりです。

POST https://<subdomain>.<domain>/apps/api/v1/sms

受信 SMS のサポート

環境でインバウンド SMS 応答をサポートする場合は、アウトバウンド番号をキューに割り当てられたインバウンド SMS 番号として設定する必要もあります。各 SMS 電話番号は 1 つのキューにのみ割り当てることができます。詳しくは、SMS チャットの一般的な設定をご覧ください。

エンドユーザーがこのように設定された SMS に返信すると、着信 SMS の電話番号が割り当てられている SMS キュー メニューに移動します。詳しくは、SMS メッセージ チャットの設定 - 電話番号をご覧ください。

API オペレーション

このセクションでは、API オペレーション、本文パラメータ、レスポンス コードの概要について説明します。

Body と Params

API リクエストの本文には、次のフィールドを含める必要があります。

フィールド名 タイプ 必須 説明 値 メモ
agent_id Integer × この ID に対応するエージェントは、指定された番号間にチャットが存在しない場合、新しいチャットに割り当てられます。エージェントが既存のチャットに接続している場合、メッセージはエージェントに代わって送信されます。
agent_email 文字列 × エージェントのメールアドレス。
chat_type 文字列 ○ SMS メッセージ SMSAP
chat_subtype 文字列 ○ api_initiated
end_user_number 文字列 ○ テキスト メッセージの送信先番号 検証: 有効な電話番号: 米国の電話番号の場合は +18882468888
outbound_number 文字列 ○ SMS メッセージの送信に使用する発信電話番号 検証: a) 電話番号はテナントに関連付けられた SMS 電話番号である必要がある、b) 電話番号がない、c) 電話番号の形式が正しくない（米国の電話番号の場合は +18882468888）
メッセージ 文字列 ○ お客様に送信される SMS メッセージ 長いメッセージ: 長いメッセージを複数のメッセージに分割する（既存のアウトバウンド SMS 機能で対応済み） 検証: a) メッセージがない、b) メッセージが最大文字数を超えている（x 文字超過）
ticket_id id × セッションを特定の CRM チケット ID に関連付けます 注: 無効なチケット ID は無視されます。

エラーと成功

ケース 想定される結果 コピー
SMS サービスが有効になっている
アウトバウンド SMS サービスが有効になっている
chat_type 値が「OutboundSMSAPI」である
end_user_number が指定され、形式が正しい
outbound_number が指定され、形式が正しい
米国の電話番号以外の場合: 米国の電話番号以外が有効になっている
メッセージが指定されている
outbound_number と end_user_number の間にアクティブなチャットがない		 成功 （200）成功レスポンスのサンプル
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
エージェント ID とエージェントのメールアドレスが提供されている エラー agent_id または agent_email のいずれか 1 つのみを指定できます。
エージェント ID またはエージェントのメールアドレスが指定されている
エージェントが既存のチャットに接続されていない		 エラー 送信 SMS が失敗しました。エージェントがチャットに接続されていません。
SMS サービスが有効になっていない エラー 「SMS サービスが無効になっています」
アウトバウンド SMS サービスが有効になっていない エラー 「Outbound SMS service is not enabled」
chat_type が指定されていません エラー 「chat_type を指定する必要があります」
chat_type が指定されているが、'sms' に設定されていない エラー 「有効な chat_type を指定する必要があります」
end_user_number が指定されているが、形式が正しくない エラー 「end_user_number is invalid」
（注: 米国の電話番号の有効な電話番号は「+18882468888」です）
end_user_number が指定されていない エラー 「end_user_number is required」
outbound_number が指定されているが、形式が正しくない エラー 「outbound_number is invalid」
（注: 有効な電話番号: 米国の電話番号の場合は「+18882468888」）
outbound_number が指定されているが、そのテナントに存在しない エラー 「outbound_number が見つかりません」
outbound_number が指定されていません エラー 「outbound_number が必要です」
outbound_number が米国外の電話番号で、「米国外の電話番号サービス」が有効になっていない エラー 「Non US phone number service is not enabled」（米国外の電話番号サービスが有効になっていません）
注: [設定] > [通話中の SMS] > [米国外の電話番号の設定] の [米国外の電話番号] の設定によって異なります。
メッセージが空です エラー 「message is required」
outbound_number と end_user_number 間のアクティブなチャット エラー 「送信 SMS に失敗しました。Consumer is already in an active SMS session."
ticket_id は入力されているが、CRM に存在しない エラー 「チケットが見つかりません」

SMS の有効期限

送信 SMS メッセージは、送信されるとすぐに有効になります。

特定のアウトバウンドの電話番号とお客様の電話番号の間で新しい SMS チャット セッションを確立するには、SMS チャットを終了する必要があります。これには、API を使用して送信された SMS メッセージも含まれます。発信者と消費者の電話番号の間に既存のアクティブなチャットがある場合、発信 SMS は失敗します。

チャットの自動タイムアウト オプション

チャットの自動タイムアウト オプションは、[設定] > [チャット] > [SMS の有効期限とグローバル タイムアウト] で設定します。チャット セッションのフローでアクティビティや進行状況がない場合に、チャット セッションがアクティブな状態を維持する期間を制御できます。

チャット ステータスの違い

チャット プロセスの状態変化の違いは次のとおりです。

  • キュー選択状態のチャットの有効期限API を使用して送信されたアウトバウンド チャットは、ユーザーが返信するまでキュー選択状態と見なされます

    キューの選択状態から先に進んでいないチャット セッション。これには、消費者が返信していない送信 SMS メッセージが含まれます。チャットがこの状態を維持できる期間を定義できます（メッセージが送信され、タイマー内に消費者が応答しない - チャットの有効期限が切れる）。

  • Unanswered SMS chat expiration (during hours of operation)（営業時間内の未回答の SMS チャットの有効期限）特定のキューの営業時間内に、チャットがキュー内で未回答のまま有効期限切れになるまでの時間。

  • Unanswered SMS chat expiration (during after hours): 特定のキューの営業時間外に、チャットがキュー内で応答なしのまま期限切れになるまでの時間。

  • アウトバウンド SMS チャットのタイムアウト: アウトバウンド SMS チャット セッションは、[x] 分間アクティビティがないと自動的に期限切れになります。

チャットのステータスの詳細

  • API を使用して送信 SMS が送信されると、チャットはアクティブと見なされますが、接続済みとは見なされません。

  • これらのアクティブなアウトバウンド SMS チャットは、お客様が返信するまでキュー選択状態と見なされます。

  • お客様が返信し、エージェントがチャットに割り当てられると、チャットは接続済みとみなされます。

チャット ステータスが適用されたタイマーに与える影響

  • API を使用して送信された、お客様からの返信がないアクティブなチャットは、キューの選択状態タイマーの対象となります。

  • エージェントに接続されたチャットには、アウトバウンドの有効期限タイマーが適用されます

  • お客様が最初のメッセージに返信してもエージェントが割り当てられない場合、チャットは接続されず、営業時間内または営業時間後に未回答チャットの有効期限タイマーの対象となります。

API メッセージ フローとステータスの例:

  1. API を使用して SMS メッセージがお客様に送信される - チャットがキュー選択状態になり、エージェントに接続されていない

  2. キュー選択状態のチャットの有効期限タイマーが開始します。タイマーのしきい値内に消費者が返信しない場合、チャットはタイムアウトして終了します。

  3. お客様がチャットに返信すると、チャットがエージェントに接続されます。

  4. お客様が最後のメッセージを送信 - アウトバウンド SMS チャットのタイムアウト タイマーが開始します。

  5. アウトバウンド SMS チャットのタイムアウト タイマーのしきい値に達したため、チャットが終了しました。

チャット終了タイマーなし - API で開始されたアウトバウンド SMS セッションの場合、チャット終了タイマーは動作しないため、消費者がメッセージに返信してチャットがインバウンド チャットとして届いた後も、チャット終了イベントは発生しません。

レスポンスの定義

API は、/calls のモデルで示されているように、単一の呼び出しオブジェクトで応答します。

Sessionless Outbound SMS API

CCAI プラットフォームには、リンクされたセッションなしでアウトバウンド SMS メッセージをサポートできるアウトバウンド SMS API が用意されています。

この API 呼び出しは、CCAI プラットフォームを使用して既存のワークフロー中にトリガーできる、セッションにリンクされていない SMS メッセージを開始します。

セッションレス SMS は、消費者に 1 回限りのメッセージを送信するだけで、CRM チケットを開く必要がない場合に適しています。

このアウトバウンド SMS API を使用すると、API 呼び出しごとに最大 500 件のメッセージを送信できます。

ユースケース

セッションレス SMS の一般的なユースケースは次のとおりです。

  • ワンタイム パスワードの設定。

  • Verification code

  • 予約のリマインダー。

  • フィードバックのリンク。

  • マーケティングやプロモーションのメッセージ。

Sessionless Outbound API と Outbound SMS API は、Outbound SMS では、消費者が応答するとアクティブなセッションが開始され、エージェントに転送できる点が異なります。ユースケース（配達通知、予約のリマインダー）は似ていますが、コンシューマーが応答したときの動作が異なります。セッションレスのデフォルトの返信不可通知が届くことがありますが、アウトバウンド SMS の場合はエージェントに転送されます。

セッションレスのアウトバウンド SMS API エンドポイント

このエンドポイントのベース URI は次のとおりです。

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

API 認証情報を追加する

  1. CCAI Platform ポータルで、[設定] > [デベロッパー設定] > [API 認証情報の管理] に移動します。

  2. [+ API 認証情報を追加] ボタンをクリックします。[API 認証情報を追加] メッセージが開きます。

  3. 認証情報の名前（名前）を入力します。

  4. [作成] をクリックします。

SMS メッセージの送信

セッションレスのアウトバウンド SMS を送信するには、POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms を呼び出し、次のリクエスト パラメータを渡します。

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
フィールド名 タイプ 必須 説明 メモ
from_phone 文字列 ○ メッセージの送信元の電話番号。 有効な米国の電話番号である必要があります。
次の場合、API 呼び出しはエラーを返します。
* 電話番号がテナントに関連付けられた SMS 電話番号ではない
* from_phone フィールドが空である
* 電話番号が正しい形式ではない。たとえば、次の番号は米国の有効な電話番号です。+18882468888
to_phones Array [String] ○ メッセージの送信先の電話番号。 API 呼び出しを成功させるには:
* +18882468888 などの有効な電話番号があることを確認します。
API 呼び出しあたりの電話番号の最大数は 100 です。
メッセージ Array [String] ○ 送信するメッセージ。 送信できる個別のメッセージの最大数は 5 件です。
各メッセージの文字数は 320 文字を超えてはなりません。

API レスポンス

API 呼び出しが成功すると、次のようになります。

  • code: 200

  • リクエスト ID

    リクエスト ID をシステムレコードに記録してください。問題のトラブルシューティングが必要な場合、サポートではリクエスト ID を使用してサポートします。

API 呼び出しが失敗すると、次のメッセージが表示されます。

  • code: 4xx

  • エラー メッセージ

SMS の制限

  • API は 1 分あたり最大 300 件のメッセージを処理します。

  • 未処理のメッセージはすべて 2 時間後に期限切れになります。