salla-communication-app

Salla コミュニケーションアプリ

コミュニケーションアプリは、SMS、メール、WhatsApp のメッセージ配信を引き継ぐアプリ機能です。ストアのイベント（注文状況の変更、OTP のリクエスト、カート放棄など）が発生すると、Salla は作成済みのメッセージを添えて関数を呼び出します。関数は context.settings からプロバイダーの認証情報を読み取り、プロバイダー（Twilio / SendGrid / 360dialog / Unifonic など）を呼び出し、Resp ユーティリティを介して結果を返します。ルーティングと配信はあなたが担い、トリガーは Salla が担います。（概要）

前提条件：App Functions の基本を理解していること（salla-app-functions）。ランタイム、Resp、サンドボックスの制限については、ここでは繰り返し説明しません。（はじめに）

ステップ 1 — アプリを作成する

type: "communication" を指定して、salla-app-builder に従います。コミュニケーションアプリのカテゴリを選択すると、サポートされる機能のセクション（ステップ 2）が表示されます。これを選択しないと、チャネルのオプションは表示されません。 （チャネル設定）一般アプリとの違い：

• sub_category_id は不要 — コミュニケーションアプリでは使用しません（使用するのは app と shipping タイプのみです）。公開時には main_category_id が必要です。これは共通の「アプリテーマ」／「アプリの影響」リスト（salla_reference action=categories → main_categories）であり、コミュニケーション専用のツリーではありません。
• デフォルトのウェブフックは 0 件 — 自動で登録されるものはありません（配送アプリにはデフォルトの配送イベントが設定されますが、コミュニケーションアプリにはありません）。
• is_embedded のデフォルト値は true です。

確認：「type: "communication" を指定してアプリを作成し、サポートされる機能のセクションが表示されましたか？」

ステップ 2 — 対応チャネルを宣言する（公開の必須条件）

対応機能では、アプリが処理するチャネルを宣言します。マーチャントがアプリをインストールし、チャネルのアクティブなハンドラーとして設定すると、Salla はデフォルトの配信レイヤーを使用せず、一致するすべてのメッセージを App Function にルーティングします。アプリがその種類のメッセージを全面的に処理することになります。公開する前に、少なくとも 1 つのチャネルを宣言する必要があります： （チャネル設定）

• MCP：salla_settings action=set_features に、sms_local、sms_international、email_all、whatsapp のいずれかを指定します。
• 現在設定されている機能を確認する：salla_settings action=list_features。（設定済みの機能のみが返され、機能タイプのスキーマ全体は返されません。有効なチャネル値 — sms_local、sms_international、email_all、whatsapp — は API レスポンスではなく、ツールのスキーマで定義されています。このツールは対応機能エンドポイントをラップしているため、エンドポイントを直接呼び出さないでください。）

機能	set_features の値	イベント	処理する内容
国内 SMS	sms_local	communication.sms.send	KSA の番号への SMS（+966…）
国際 SMS	sms_international	communication.sms.send	KSA 以外への SMS
メール	email_all	communication.email.send	すべてのメール
WhatsApp	whatsapp	communication.whatsapp.send	すべての WhatsApp

機能を設定せずに公開すると、403 communication_app_not_have_features エラーになります （スラッグとチャネルの値は salla_settings ツールのスキーマで確認できます。値が変更された場合は、Partners MCP または Portal で最新の値を確認してください）。

SMS アプリを公開するには CITC 認証が必要です。 SMS に対応するコミュニケーションアプリ（sms_local / sms_international）は、アカウント確認フォーム（https://portal.salla.partners/account）で CITC 認証をアップロードする必要があります。これはサウジアラビアの規制要件です。 アプリの詳細には requires_citc（app_publish action=get / salla_apps action=get）が表示されます。値が true の場合、証明書が引き続き必要です。パートナーが公開リクエストを行う前にアカウントを確認し、証明書をアップロードします。それまでは送信がブロックされます。公開フロー → salla-publication-consistency。

確認条件：「salla_settings action=set_features で少なくとも 1 つのチャネルを宣言済み — SMS アプリの場合は requires_citc が false になっていること」

ステップ 3 — プロバイダーを設定する

コードを書く前に、配信プロバイダーを選び、認証情報を取得します。ドキュメントでは、実例として Twilio を説明しています（プロバイダー／Twilio）：アカウントを作成し、電話番号を取得して、Account SID、Auth Token、送信者番号を保存します（WhatsApp の場合は、本人確認済みの番号から Twilio サンドボックスに参加します。テスト中は、確認済みのサンドボックス番号にのみメッセージが届きます）。同じ手順は他のプロバイダー（SendGrid API キー、Meta Graph トークンと電話番号 ID など）にも適用できます。異なるのはフィールド名だけです。

これらは各マーチャントが個別に入力できるよう、App Settings として設定します。ハードコードしないでください。設定 FORM の定義（フィールドスキーマ、シークレット用の public:false）は salla-app-settings にあり、実行時には context.settings として渡されます。

Step 4 — アプリ関数を作成する

3 つのイベントは アプリ関数のトリガー です。フック可能なルールに従い、Webhook ではなくアプリ関数（salla-app-functions）として実装します。サーバーは不要で、マーチャントのプロバイダー認証情報は context.settings に渡されます。

Portal の関数ビルダーで Select Action をクリックし、処理したいチャネルイベントを選択します。チャネルごとに 1 つの関数を作成するか、context.payload.event に応じて分岐する単一のマスター関数を作成します。ハンドラーはペイロードと設定を読み取り、プロバイダーを呼び出し、Resp.success() / Resp.error() を返します。

export default async (context: CommunicationEvent): Promise<Resp> => {
  const { payload, settings } = context;
  const { notifiable, content } = payload.data;

  if (!settings.sms_api_key) {
    return Resp.error()
      .setMessage("Missing provider credentials.")
      .setStatus(422);
  }
  try {
    const res = await fetch(`${settings.sms_base_url}/send`, {
      method: "POST",
      signal: AbortSignal.timeout(10_000),
      headers: {
        Authorization: `Bearer ${settings.sms_api_key}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ to: notifiable[0], text: content }),
    });
    return res.ok ? Resp.success() : Resp.error().setStatus(res.status);
  } catch (err: any) {
    return Resp.error().setMessage("Delivery failed.").setStatus(500);
  }
};

すべてのイベントで、同じペイロードが context.payload.data（notifiable、type、content、entity、meta）に渡され、認証情報は context.settings に渡されます。Local SMS と International SMS は、単一の communication.sms.send イベントを共有します。プロバイダー固有の処理が必要な場合は、notifiable[0] の電話番号のプレフィックスに応じて振り分けます。イベント一覧、型定義、実例、処理パターンの全容については、references/communication-events.md を参照してください。

配信を自社インフラで実行する必要がある場合に限り、これらのイベントに対する Webhook サブスクリプションを代わりに使用してください（salla-webhooks）。

このアプリは実際の顧客にメッセージを送信するため、content、notifiable、settings の認証情報をログに記録しないでください。また、呼び出す前にプロバイダーのエンドポイントを検証してください。シークレットと個人を特定できる情報に関するルールの全容は、references/communication-events.md を参照してください。

ゲート：「各チャネルが、context.settings から認証情報を読み取り、Resp.success() / Resp.error() を返すアプリ関数で処理されているか。ハードコードされたキーや独自サーバーは使っていないか。」

Step 5 — テストする

2 段階で行います（Test & Go Live）。

1. プレビュー画面 — 関数エディターで Select Store（デモストア）を選択し、プレビュー用パラメーター（通常は、電話番号が確認済みのテスト番号である顧客 ID）を入力してから、Save and Preview を選択します。画面には実行ステータス、返されたデータ、実行時間、console.log() の出力、エラートレースが表示されます。context.settings が空の場合は、デモストアの App Settings フォームに入力していません。プレビューには salla-app-functions-test を使用してください。
2. ダッシュボードからエンドツーエンドでテスト — デモストアにインストールし、Apps → Settings → Customize でアプリを有効なハンドラーとして設定してから、実際のメッセージを発生させます（例：注文ステータスを変更して communication.*.send を発火させます）。その後、プロバイダー経由でメッセージが届くことを確認します。デモストアでのテスト全体については、salla-live-testing を参照してください。

ゲート：「デモストアからの実際の communication.*.send イベントが、プロバイダー経由でエンドツーエンドに配信されたか。」

Step 6 — 公開する

salla-app-builder を使用して、通常の公開手順を実行します。ゲート：Step 2 の機能が設定され、送信ハンドラーが上記 2 段階のテストに合格していること。編集内容は公開するまでサンドボックス内にとどまります。すでにアプリをインストールしているマーチャントには、公開後に更新済みの関数が自動的に適用されます。再インストールは不要です。 (Test & Go Live)

注意すべき誤解

誘惑に駆られる考え	それが誤りである理由
「コードが動いてから、対応する機能を宣言しよう。」	チャネルを何も宣言せずに公開すると、403 communication_app_not_have_features が発生します。公開前に salla_settings action=set_features を使って 1 つ以上宣言してください（ステップ 2）。
「SMS アプリは配信が動作すれば、提出できる状態だ。」	SMS アプリ（sms_local／sms_international）は、アカウント認証フォームに CITC 証明書がアップロードされるまでブロックされたままです。まず requires_citc が false であることを確認してください（ステップ 2）。
「送信イベントを受信するために、Webhook サーバーを立ち上げよう。」	送信イベントは App Function トリガーです。App Functions として実装してください（サーバーは不要です。認証情報は context.settings に届きます）。配信を独自のインフラ上で実行する必要がある場合にのみ、Webhook を使用してください（ステップ 4）。
「プロバイダーのキーを自分のデータベースに保存しよう。」	プロバイダーの認証情報は、実行時に context.settings から読み取る マーチャントごとの App Settings です。ハードコードしたり、salla_settings 以外に保存したりしないでください（ステップ 3）。

リソース

トピック	リンク
概要	https://docs.salla.dev/2006115m0.md
はじめに	https://docs.salla.dev/2006118m0.md
アプリチャネルの設定	https://docs.salla.dev/2081234m0.md
プロバイダーの設定（Twilio）	https://docs.salla.dev/2081235m0.md
App Function の構築	https://docs.salla.dev/2081248m0.md
テストと公開	https://docs.salla.dev/2081250m0.md
イベントとペイロードのリファレンス	https://docs.salla.dev/2006119m0.md
例	https://docs.salla.dev/2006120m0.md