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

発信の作成と管理

このガイドでは、発信を管理するために API を使用する手順をステップごとに説明します。

注意: 認証の詳細については、｢はじめに > 認証｣ のセクションで説明しています。OAuth2トークンの取得と使用についてはこのセクションを参照してください。

ステップ 1: キャンペーンを作成する​

⚠️ 注意: この要素は現在 Mico Voice AI の UI には表示されませんが、API 経由で作成・管理することができます。2025 年後半に予定されているプラットフォームの大規模アップデートの一部として、インターフェースで利用可能になる予定です。

キャンペーンとは、スケジュールと発信が含まれる最上位の要素です。

注意: 既存のコールフローを使用している場合はこの手順を省略し、Get CallFlow エンドポイントを使用して関連するキャンペーン UID を取得できます:

curl -X GET https://api.micovoice.com/api/v1/call_flows/YOUR_CALLFLOW_UID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

レスポンスには次のステップで使用できる campaign_uid フィールドが含まれます。

既存のキャンペーンがない場合は次の手順で作成する必要があります:

curl -X POST https://api.micovoice.com/api/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "My First Campaign",
    "is_enabled": true,
    "type": "scheduled_call"
  }'

予想されるレスポンス (ステータス: 201)​

{
  "uid": "09c83f1c-3489-4ac2-876c-bb6d7f3321bf",
  "name": "My First Campaign",
  "is_enabled": true,
  "created_at": "2025-04-16T12:00:00Z",
  "updated_at": "2025-04-16T12:00:00Z"
}

レスポンスから uid を保存します - スケジュールの作成に必要です。

ステップ 2: スケジュールを作成する​

⚠️ 注意: この要素は現在 Mico Voice AI の UI には表示されませんが、API 経由で作成・管理することができます。2025 年後半に予定されているプラットフォームの大規模アップデートの一部として、インターフェースで利用可能になる予定です。

スケジュールでは、発信がいつ行われ、どのように再試行が処理されるかを定義します。

curl -X POST https://api.micovoice.com/api/v1/campaigns/09c83f1c-3489-4ac2-876c-bb6d7f3321bf/schedules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "Morning Calls",
    "starts_at": "2025-04-17T09:00:00Z",
    "ends_at": "2025-04-17T12:00:00Z",
    "retry_type": "consistent",
    "retry_intervals": [300, 300, 300]
  }'

予想されるレスポンス (ステータス: 201)​

{
  "uid": "096c36c45-b95c-4ab1-8bb1-6e6e1283c950",
  "name": "Morning Calls",
  "starts_at": "2025-04-17T09:00:00Z",
  "ends_at": "2025-04-17T12:00:00Z",
  "retry_type": "consistent",
  "retry_intervals": [300, 300, 300],
  "is_enabled": false,
  "is_auto": false,
  "created_at": "2025-04-16T12:05:00Z",
  "updated_at": "2025-04-16T12:05:00Z"
}

レスポンスからスケジュール uid を保存します - 発信の作成に必要です。

ステップ 3: 発信を作成する​

キャンペーンとスケジュールを設定したら、個別または一括で発信を作成できます。

重要: コールの作成は、スケジュールが有効になっていない場合にのみ機能します。 または、コールを作成する際に force=true クエリパラメータを使用して、この制限を回避することもできます。

ステップ 3A: 単一の発信を作成する​

詳細な発信先情報とカスタムパラメーターで個別の発信を作成できます。

curl -X POST https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "phone_number": "+818012345678",
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "phonetic_full_name": "John Doe",
    "phonetic_first_name": "John",
    "phonetic_last_name": "Doe",
    "email": "john.doe@example.com",
    "custom_parameters": {
      "account_id": "A12345",
      "appointment_time": "3:30 PM"
    },
    "external_id": "CUST-123"
  }'

単一のコール作成詳細​

  • 必要なフィールド:

    • phone_number: 発信先の電話番号
    • first_name: 発信先の（名）
    • last_name: 発信先の（姓）
    • phonetic_first_name: よみがな（名）
    • phonetic_last_name: よみがな（姓）

  • オプションのフィールド:

    • full_name: 発信先の (氏名)
    • phonetic_full_name: よみがな（氏名）
    • email: 発信先メールアドレス
    • event_date_time: 関連イベントのタイムスタンプ
    • custom_parameters: 任意のカスタムキーと値のペアを含むオブジェクト
    • external_id: このコールに対するシステムの識別子

  • 強制パラメータ: オプションのクエリパラメータ force=true を使用すると、スケジュールで有効になっているステータスチェックを回避することができます。

予想されるレスポンス (ステータス: 201)​

{
  "uid": "d26a3041-1743-413f-9722-04ac1f612960",
  "external_id": "CUST-123",
  "status": "pending",
  "progress": "in_queue",
  "is_test_call": false,
  "number_call_retries": 3,
  "cooldown_until": null,
  "created_at": "2025-04-16T12:10:00Z",
  "updated_at": "2025-04-16T12:10:00Z",
  "outbound_call_info": {
    "phone_number": "5551234567",
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "phonetic_full_name": "John Doe",
    "phonetic_first_name": "John",
    "phonetic_last_name": "Doe",
    "email": "john.doe@example.com",
    "custom_parameters": {
      "account_id": "A12345",
      "appointment_time": "3:30 PM"
    }
  },
  "outbound_call_attempts": [],
  "outbound_calls_notifications": []
}

今後の参照用に、発信 uid を保存します。

ステップ 3B: 一括の発信を作成する​

効率化のために、一度に複数の発信を作成することができます。バルクエンドポイントでは、1 回のリクエストで最大 1,000 コールまで作成できます。

curl -X POST https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "outbound_calls": [
      {
        "phone_number": "5551234567",
        "full_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "phonetic_full_name": "John Doe",
        "phonetic_first_name": "John",
        "phonetic_last_name": "Doe",
        "email": "john.doe@example.com",
        "custom_parameters": {
          "appointment_id": "APT-789"
        },
        "external_id": "CUST-123"
      },
      {
        "phone_number": "+818098765431",
        "full_name": "Jane Smith",
        "first_name": "Jane",
        "last_name": "Smith",
        "phonetic_full_name": "Jane Smith",
        "phonetic_first_name": "Jane",
        "phonetic_last_name": "Smith",
        "email": "jane.smith@example.com",
        "custom_parameters": {
          "appointment_id": "APT-456"
        },
        "external_id": "CUST-456"
      }
    ]
  }'

一括作成の詳細​

  • 最大バッチサイズ: 1 回の一括リクエストに最大 1,000 件の発信を含めることができます
  • 最小バッチサイズ: 少なくとも 1 つの発信が必要です
  • 必須フィールド: 各発信には、単一の作成エンドポイントと同じフィールドが必要です
  • 強制パラメータ: オプションのクエリパラメータ force=true を使用すると、スケジュールで有効になっているステータスチェックを回避することができます。

予想されるレスポンス (ステータス: 201)​

{
  "outbound_calls": [
    {
      "uid": "d26a3041-1743-413f-9722-04ac1f612960",
      "external_id": "CUST-123",
      "status": "pending",
      "progress": "in_queue"
    },
    {
      "uid": "7f93b218-5c22-476a-9321-e9712fdcb490",
      "external_id": "CUST-456",
      "status": "pending",
      "progress": "in_queue"
    }
  ],
  "total_count": 2,
  "successful_count": 2,
  "failed_count": 0,
  "failures": []
}

一括作成中に何らかのコールが失敗した場合、レスポンスでは failures 配列に詳細が含まれます:

{
  "outbound_calls": [...],
  "total_count": 3,
  "successful_count": 2,
  "failed_count": 1,
  "failures": [
    {
      "index": 2,
      "reason": "Invalid phone number format",
      "details": {
        "phone_number": "Invalid format"
      }
    }
  ]
}

この一括操作では、成功した各コールの UID と失敗したコールの詳細を含む、作成されたコールのサマリーが返されます。

Step 4: スケジュールを有効化​

特定のスケジュールに対して発信を作成したあと、そのスケジュールを有効化する必要があります：

curl -X PATCH https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "is_enabled": true,
  }'

予想されるレスポンス (ステータス: 200)​

{
  "uid": "096c36c45-b95c-4ab1-8bb1-6e6e1283c950",
  "name": "Morning Calls",
  "starts_at": "2025-04-17T09:00:00Z",
  "ends_at": "2025-04-17T12:00:00Z",
  "retry_type": "consistent",
  "retry_intervals": [300, 300, 300],
  "is_enabled": true,
  "is_auto": false,
  "created_at": "2025-04-16T12:05:00Z",
  "updated_at": "2025-04-16T12:05:00Z"
}

ステップ 5: 発信をリストする​

スケジュールに関連付けられている全発信を取得する手順:

curl -X GET https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

フィルタリングオプション​

API は、特定のコールを検索するために役立つ幅広いフィルタリング機能を提供します:

パラメータ説明例
outcome通話結果によるフィルタリングoutcome=Transfer%20to%20agent
attempt_status通話試行ステータスによるフィルタリングattempt_status=hangup
external_id参照 ID によるフィルタリングexternal_id=CUST-123
is_test_callテストコールを含む/含まないis_test_call=true
first_name発信先の（名）でフィルタリングfirst_name=John
last_name発信先の（姓）でフィルタリングlast_name=Doe
phonetic_first_name名前のよみがな（名）でフィルタリングphonetic_first_name=John
phone_number発信先の電話番号でフィルタリングphone_number=%2B818012345678
email発信先のメールアドレスでフィルタリングemail=john.doe@example.com

ページ付け​

大規模なデータセットを管理するために、レスポンスはページ付けされます:

  • page: どのページを返すか (デフォルト: 1)
  • page_size: ページあたりの結果数 (デフォルト: 50, 最大: 100)

フィルタリングとページ付けの例

curl -X GET "https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?attempt_status=hangup&page=2&page_size=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

予想されるレスポンス (ステータス: 200)​

[
  {
    "uid": "d26a3041-1743-413f-9722-04ac1f612960",
    "external_id": "CUST-123",
    "status": "pending",
    "progress": "in_queue",
    "is_test_call": false,
    "number_call_retries": 3,
    "cooldown_until": null,
    "created_at": "2025-04-16T12:10:00Z",
    "updated_at": "2025-04-16T12:10:00Z",
    "outbound_call_info": {
      "phone_number": "5551234567",
      "full_name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "phonetic_full_name": "John Doe",
      "phonetic_first_name": "John",
      "phonetic_last_name": "Doe",
      "email": "john.doe@example.com",
      "custom_parameters": {
        "account_id": "A12345",
        "appointment_time": "3:30 PM"
      }
    },
    "outbound_call_attempts": [],
    "outbound_calls_notifications": []
  },
  ...
]

ステップ 6: 発信に関する詳細を取得する​

すべての通話試行と通話結果を含む、特定の発信に関する総合的な情報を取得する手順:

curl -X GET https://api.micovoice.com/api/v1/outbound_calls/d26a3041-1743-413f-9722-04ac1f612960 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

レスポンスに含まれる内容​

レスポンス詳細には、コールに関する全情報が含まれています。

  1. 基本情報
    • UID、外部 ID、作成および更新のタイムスタンプ
    • 現状と進捗状況
    • テストコールのフラグと再試行情報
  2. 発信先情報 (outbound_call_info)
    • すべての発信先詳細 (名前、電話番号、メールアドレス)
    • コール作成時に提供されたカスタムパラメータ
  3. 通話試行 (outbound_call_attempts)
    • 発信先への各試行履歴
    • 開始、応答、終了のタイムスタンプ
    • 接続された通話の時間
    • 各通話試行の状況と結果
    • 該当する場合、エラーの詳細
  4. 通知 (outbound_calls_notifications)
    • 通話に関連して送信された通知の状況
    • メッセージ数と配信状況

予想されるレスポンス (ステータス: 200)​

{
  "uid": "d26a3041-1743-413f-9722-04ac1f612960",
  "external_id": "CUST-123",
  "status": "completed",
  "progress": "answered",
  "is_test_call": false,
  "number_call_retries": 0,
  "cooldown_until": null,
  "created_at": "2025-04-16T12:10:00Z",
  "updated_at": "2025-04-16T12:15:30Z",
  "outbound_call_info": {
    "phone_number": "5551234567",
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "phonetic_full_name": "John Doe",
    "phonetic_first_name": "John",
    "phonetic_last_name": "Doe",
    "email": "john.doe@example.com",
    "custom_parameters": {
      "account_id": "A12345",
      "appointment_time": "3:30 PM"
    }
  },
  "outbound_call_attempts": [
    {
      "uid": "8ae20b12-ebaa-47f4-822f-2b7e3f388f49",
      "status": "hangup",
      "started_at": "2025-04-16T12:12:00Z",
      "answered_at": "2025-04-16T12:12:15Z",
      "ended_at": "2025-04-16T12:15:30Z",
      "duration": 195,
      "created_at": "2025-04-16T12:11:00Z",
      "updated_at": "2025-04-16T12:15:30Z",
      "error_details": null,
      "outbound_call_attempts_outcomes": [
        {
          "call_outcome": {
            "uid": "6a938cdf-9b4b-4e8c-940b-05af78ea8666",
            "name": "APPOINTMENT_CONFIRMED"
          },
          "created_at": "2025-04-16T12:15:00Z"
        }
      ]
    }
  ],
  "outbound_calls_notifications": [
    {
      "uid": "8ae20b12-ebaa-47f4-822f-2b7e3f388f49",
      "status": "delivered",
      "message_count": 1
    }
  ]
}