> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 送信メッセージとテンプレート

## 概要

エージェントが自由形式のWhatsAppメッセージを送信できるのは、アクティブな会話内のみです。通知、再エンゲージメント、予定された通話などで先にユーザーへ連絡するには、Metaが承認した**メッセージテンプレート**を送信します。このページでは、テンプレートの作成、アウトバウンドメッセージと通話の送信、そして大規模な運用について説明します。

## WhatsApp Managerでテンプレートを作成する

テンプレートの作成と承認はElevenLabsではなく、[WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates)で行います。

テンプレートを作成する際は、以下を行ってください。

* カテゴリを選択します。取引メッセージには**Utility**、プロモーションメッセージには**Marketing**、認証コードには**Authentication**を選択します。Metaではカテゴリごとに料金とレート制限が異なります。詳しくは[WhatsAppの料金](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)を確認してください。
* パラメータ形式を選択します。位置指定（`{{1}}`、`{{2}}`）または名前付き（`{{customer_name}}`）です。名前付きパラメータでは、送信する各値に`parameter_name`が必要です。
* 承認を申請します。通常、承認には数分から数時間かかります。保留中または却下されたテンプレートは送信できません。APIはリクエストを受け付けますが、Metaはメッセージを配信しません。

> **Note**
>
> Metaは、1人のユーザーが一定期間内に受信できる[マーケティングテンプレート ](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits)
> の数を制限しています。マーケティングテンプレートが通知なく配信されない場合、この制限がよくある原因です（Metaエラー131049）。

## アウトバウンドメッセージを送信する

テンプレートメッセージを送信すると、新しい会話が開始されます。ユーザーが返信するまでエージェントは応答しません。テンプレート自体が最初のメッセージであり、ユーザーが応答するまで会話タイマーは開始されません。

#### ダッシュボード

[WhatsAppページ](https://elevenlabs.io/app/agents/whatsapp)に移動し、アカウントを選択して、***Outbound -> Message***ボタンをクリックします。エージェントを選択し、WhatsAppユーザーIDを入力して、メッセージテンプレートとそのパラメータを選択します。

![WhatsAppのアウトバウンドメッセージダイアログ](/docs/_fern-img/13913c2ccc1d92cb59e7332b6fdb4a8c8c64760a334d1a311fa2007831eeb986.webp)

#### Python

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.whatsapp.outbound_message(
    whatsapp_phone_number_id="524029457612345",
    whatsapp_user_id="12213231492",
    template_name="welcome",
    template_language_code="en",
    template_params=[
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "parameter_name": "name",
                    "text": "Daniele",
                }
            ],
        }
    ],
    agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
    conversation_initiation_client_data={
        "dynamic_variables": {"customer_name": "Daniele"},
    },
)
```

#### TypeScript

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.whatsapp.outboundMessage({
  whatsappPhoneNumberId: "524029457612345",
  whatsappUserId: "12213231492",
  templateName: "welcome",
  templateLanguageCode: "en",
  templateParams: [
    {
      type: "body",
      parameters: [
        {
          type: "text",
          parameterName: "name",
          text: "Daniele",
        },
      ],
    },
  ],
  agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
  conversationInitiationClientData: {
    dynamicVariables: { customer_name: "Daniele" },
  },
});
```

#### cURL

```bash
curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_phone_number_id": "524029457612345",
    "whatsapp_user_id": "12213231492",
    "template_name": "welcome",
    "template_language_code": "en",
    "template_params": [
      {
        "type": "body",
        "parameters": [
          {"type": "text", "parameter_name": "name", "text": "Daniele"}
        ]
      }
    ],
    "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
    "conversation_initiation_client_data": {
      "dynamic_variables": {"customer_name": "Daniele"}
    }
  }'
```

完全なリクエストスキーマについては、[APIリファレンス](/docs/ja/api-reference/whats-app/outbound-message)を確認してください。

> **Tip**
>
> AIアシスタントは、これらの例をテンプレートに合わせて調整できます。ElevenLabsドキュメントの
> [llms.txt](/docs/ja/llms.txt)（またはより詳細な[llms-full.txt](/docs/ja/llms-full.txt)）を参照させ、WhatsApp Managerの
> テンプレート定義を貼り付けてリクエストを求めてください。テンプレートに適した`template_params`を含むcURL
> コマンドまたはSDK呼び出しが生成されます。

### テンプレートパラメータ

`template_params`は、パラメータを持つテンプレートコンポーネントごとに1つずつ含む、**コンポーネント**オブジェクトのリストです。

* 本文プレースホルダーには`{"type": "body", "parameters": [...]}`
* パラメータ化されたヘッダー（テキスト、画像、ドキュメント、位置情報）には`{"type": "header", "parameters": [...]}`
* ボタンパラメータには`{"type": "button", "sub_type": ..., "index": ..., "parameters": [...]}`

`parameters`の各エントリは、`{"type": "text", "text": "Daniele"}`のような値オブジェクトです。名前付きパラメータを使用するテンプレートでは、各値に`parameter_name`を含めてください。たとえば`{"type": "text", ...}`を`template_params`に直接渡すなど、コンポーネントラッパーを省略すると拒否されます。

### 受信者番号の形式

`whatsapp_user_id`には、国番号に続けて数字のみを含める必要があります。`+`、スペース、ハイフンは使用できません。たとえば、`+1 (415) 555-2671`ではなく`14155552671`です。

> **Warning**
>
> 国によっては、WhatsAppが人物に使用するIDが、その人のダイヤル番号と異なります。たとえばメキシコの番号では国番号の後に追加の`1`が付き（`521...`）、ブラジルの番号では9桁目を含む場合と含まない場合があります。ユーザーから以前にメッセージを受け取っている場合は、会話履歴からコピーできる、その以前の会話の`whatsapp_user_id`を使用してください。

### 動的変数、ブランチ、環境

`conversation_initiation_client_data`フィールドでは、会話の[動的変数](/docs/ja/eleven-agents/customization/personalization/dynamic-variables)を設定し、特定の[エージェントブランチ](/docs/ja/eleven-agents/operate/versioning)と[環境](/docs/ja/eleven-agents/integrate/environment-variables)に固定できます。

```json
{
  "dynamic_variables": { "customer_name": "Daniele" },
  "branch_id": "agtbrch_8721kwarbs83e233mg1fzkaf9pg0",
  "environment": "staging"
}
```

これらの設定は会話中維持されます。ユーザーが返信すると、エージェントは指定されたブランチと環境で再開します。ブランチと環境は最初に検証され、どちらかが存在しない場合、リクエストはエラーになりメッセージは送信されません。

このリクエストフィールドにより、アウトバウンド会話に動的変数を渡します。インバウンド会話では、代わりに会話開始Webhookから受け取ります。詳しくは[初期化コンテキスト](/docs/ja/eleven-agents/whatsapp#initialization-context)を参照してください。

> **Note**
>
> テンプレートパラメータはテンプレートテキストにのみ値を挿入し、エージェントには公開されません。エージェントがテンプレート内の値（顧客名など）を必要とする場合は、`dynamic_variables`でもう一度渡してください。

### 送信後

リクエストが成功すると`conversation_id`が返され、レンダリングされたテンプレートが最初のメッセージとして会話履歴に表示されます。ユーザーが返信するまでエージェントは実行されません。テンプレートの送信では、最大継続時間タイマーも非アクティブタイマーも開始されません。どちらも会話の再開後に開始します。`200`レスポンスはElevenLabsがリクエストを受け付けたことを意味しますが、その後Metaが配信を拒否する可能性はあります。メッセージが届かない場合は、[トラブルシューティング](/docs/ja/eleven-agents/whatsapp/troubleshooting)を確認してください。

## アウトバウンド通話をスケジュールする

アウトバウンドWhatsApp通話にはユーザーの許可が必要です。詳しくは[ユーザー通話の許可](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions)を参照してください。[WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates)で、**通話許可リクエスト**コンポーネントを含むメッセージテンプレートを作成します。通話をスケジュールすると、ElevenLabsは許可状態を確認します。

* すでに許可されている場合：すぐに通話を発信します。
* まだ許可をリクエストしていない場合：許可リクエストテンプレートを送信し、ユーザーが承認するとすぐに通話を発信します。
* 許可が拒否された場合：会話は`User declined the call permission request.`という理由で失敗として記録されます。

#### ダッシュボード

[WhatsAppページ](https://elevenlabs.io/app/agents/whatsapp)に移動し、アカウントを選択して、***Outbound -> Call***ボタンをクリックします。エージェントを選択し、WhatsAppユーザーIDを入力して、通話許可リクエストテンプレートを選択します。

![WhatsAppのアウトバウンド通話ダイアログ](/docs/_fern-img/1fcf7968f1651ce8e9474e770aad4dce4e702c69b4522f5bcc65efcd8bf8a3e4.webp)

#### Python

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.whatsapp.outbound_call(
    whatsapp_phone_number_id="524029457612345",
    whatsapp_user_id="12213231492",
    whatsapp_call_permission_request_template_name="call_permission",
    whatsapp_call_permission_request_template_language_code="en",
    agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
    conversation_initiation_client_data={
        "dynamic_variables": {"customer_name": "Daniele"},
    },
)
```

#### TypeScript

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.whatsapp.outboundCall({
  whatsappPhoneNumberId: "524029457612345",
  whatsappUserId: "12213231492",
  whatsappCallPermissionRequestTemplateName: "call_permission",
  whatsappCallPermissionRequestTemplateLanguageCode: "en",
  agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
  conversationInitiationClientData: {
    dynamicVariables: { customer_name: "Daniele" },
  },
});
```

#### cURL

```bash
curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_phone_number_id": "524029457612345",
    "whatsapp_user_id": "12213231492",
    "whatsapp_call_permission_request_template_name": "call_permission",
    "whatsapp_call_permission_request_template_language_code": "en",
    "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
    "conversation_initiation_client_data": {
      "dynamic_variables": {"customer_name": "Daniele"}
    }
  }'
```

完全なリクエストスキーマについては、[APIリファレンス](/docs/ja/api-reference/whats-app/outbound-call)を確認してください。アウトバウンドメッセージと同様に、`conversation_initiation_client_data`で動的変数を設定し、会話をブランチと環境に固定します。不明なブランチまたは環境は、通話をスケジュールする前に拒否されます。

> **Note**
>
> Metaは、アウトバウンド通話、および[カスタマーサービスウィンドウ ](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows)
> 外で送信された通話許可リクエストに料金を請求します。通話をスケジュールする前に、WhatsApp Managerで支払い方法を追加してください。

## キャンペーンとバッチ処理

多数のユーザーに通話するには、`whatsapp_params`を使用した[バッチ通話](/docs/ja/eleven-agents/phone-numbers/batch-calls)を利用します。電話番号IDと通話許可リクエストテンプレートを一度指定し、受信者ごとに`whatsapp_user_id`を指定します。

現在、アウトバウンドメッセージ用のネイティブなバッチエンドポイントはありません。テンプレートキャンペーンでは、受信者ごとに[アウトバウンドメッセージエンドポイント](/docs/ja/api-reference/whats-app/outbound-message)を呼び出し、番号に対するMetaのメッセージング制限を守ってください。詳しくは[メッセージング制限](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/messaging-limits)を参照してください。