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

発信の作成と管理

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

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

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

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

注意: 既存のコールフローを使用している場合はこの手順を省略し、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",
    "type": "scheduled_call"
  }'

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

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

注意: is_enabled は作成時に指定できません - リクエストに含めると 400 で拒否されます。新規キャンペーンは常に is_enabled: false で返されます。direction を省略した場合は outbound になります。

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

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

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

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": "96c36c45-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/96c36c45-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"
  }'

発信作成の詳細​

  • custom_parameters の日時の値は、タイムゾーン付きの ISO 8601 形式で指定してください (例: 2025-10-01T08:03:00+09:00、2025-10-01T08:03:00Z)。

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

{
  "uid": "d26a3041-1743-413f-9722-04ac1f612960",
  "external_id": "CUST-123",
  "status": "pending",
  "progress": "in_queue",
  "is_test_call": false,
  "cooldown_until": null,
  "delay": null,
  "priority": null,
  "retry_intervals": [300, 300, 300],
  "attempts_remaining": 4,
  "created_at": "2025-04-16T12:10:00Z",
  "updated_at": "2025-04-16T12:10:00Z",
  "outbound_call_info": {
    "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",
    "event_date_time": null,
    "external_id": "CUST-123",
    "custom_parameters": {
      "1024": "A12345",
      "1025": "3:30 PM"
    }
  },
  "outbound_call_attempts": [],
  "call_notifications": []
}

このレスポンスについての注意点:

  • retry_intervals と attempts_remaining はスケジュールから導出されます。再試行間隔が 3 つの場合、発信は合計 4 回になります。
  • このエンドポイントでは custom_parameters のキーがカスタムパラメータ名ではなく、コールフローのカスタムパラメータの数値 ID になります。ステップ 5 とステップ 6 の GET エンドポイントでは、同じ値がパラメータ名をキーとして返されます。

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

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

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

curl -X POST https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "outbound_calls": [
      {
        "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": {
          "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 つの発信が必要です
  • 必須フィールド: 各発信には、単一の作成エンドポイントと同じフィールドが必要です

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

一括エンドポイントは、作成された発信の UID のみをリクエストと同じ順序で返します:

{
  "data": [
    "d26a3041-1743-413f-9722-04ac1f612960",
    "7f93b218-5c22-476a-9321-e9712fdcb490"
  ]
}

作成された発信の完全な内容が必要な場合は、GET /api/v1/outbound_calls/{uid} (ステップ 6) を使用してください。

一部の失敗 (ステータス: 400)​

一括作成は全件成功か全件失敗のいずれかです。1 件でも不正な発信が含まれている場合、どの発信も作成されず、リクエストは 400 で失敗します。各エラーは outbound_calls 配列内のインデックスで該当の発信を示します:

{
  "title": "Invalid request",
  "detail": "One or more of the request parameters is invalid",
  "errors": [
    {
      "title": "Invalid value",
      "source": {
        "pointer": "/outbound_calls/1/phone_number"
      },
      "detail": "The phone number is invalid. Please use the correct format (e.g. 08012345678)"
    }
  ]
}

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

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

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

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

{
  "uid": "96c36c45-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/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

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

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

パラメータ説明例
statusコールのステータスによるフィルタリングstatus=pending,completed
progressコールの進捗によるフィルタリングprogress=answered,unanswered
sourceコールの作成元によるフィルタリングsource=api,quick_call_api
attempt_status通話試行ステータスによるフィルタリングattempt_status=no_answer,busy
outcome通話結果名によるフィルタリングoutcome=Transfer%20to%20agent
external_id参照 ID によるフィルタリングexternal_id=CUST-123
is_test_callテストコールを含む/含まないis_test_call=true
full_name発信先の氏名でフィルタリングfull_name=john%20doe
first_name発信先の（名）でフィルタリングfirst_name=john
last_name発信先の（姓）でフィルタリングlast_name=doe
phonetic_full_name名前のよみがな（氏名）でフィルタリングphonetic_full_name=john%20doe
phonetic_first_name名前のよみがな（名）でフィルタリングphonetic_first_name=john
phonetic_last_name名前のよみがな（姓）でフィルタリングphonetic_last_name=doe
email発信先のメールアドレスでフィルタリングemail=john.doe@example.com
updated_after指定時刻以降に更新されたコールのみを返すupdated_after=2026-08-01T00:00:00Z

フィルタの一致条件:

  • status、progress、source、attempt_status はカンマ区切りで複数の値を指定できます。いずれかの値に一致するコールが返されます。
  • 氏名・よみがな・メールアドレスのフィルタは部分一致で、大文字小文字を区別しません。たとえば last_name=do は Doe にも一致します。
  • external_id と outcome は保存されている値と完全に一致する必要があります。
  • updated_after には RFC 3339 形式のタイムスタンプを指定します。境界を含み (updated_at >= 指定値)、指定するとレスポンスの並び順が updated_at の昇順に切り替わります。ページ送りの途中で更新されたコールはスキップされずに再度読み込まれるため、差分同期にはこのパラメータを使用してください。
  • ここに記載されていないクエリパラメータは、Unexpected field: <name> エラーとともに 400 で拒否されます。

ページ付け​

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

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

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

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

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

発信は pagination オブジェクトとともに data の下に返されます。該当するページが存在しない場合、next と prev は null になります。

{
  "data": [
    {
      "uid": "d26a3041-1743-413f-9722-04ac1f612960",
      "external_id": "CUST-123",
      "status": "pending",
      "progress": "in_queue",
      "is_test_call": false,
      "cooldown_until": null,
      "delay": null,
      "priority": null,
      "retry_intervals": [300, 300, 300],
      "attempts_remaining": 4,
      "created_at": "2025-04-16T12:10:00Z",
      "updated_at": "2025-04-16T12:10:00Z",
      "outbound_call_info": {
        "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",
        "event_date_time": null,
        "external_id": "CUST-123",
        "custom_parameters": {
          "account_id": "A12345",
          "appointment_time": "3:30 PM"
        }
      },
      "outbound_call_attempts": [],
      "call_notifications": []
    }
  ],
  "pagination": {
    "total_count": 62,
    "total_pages": 3,
    "page_size": 25,
    "current_page": 2,
    "links": {
      "self": "https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page_size=25&page=2",
      "next": "https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page_size=25&page=3",
      "prev": "https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page_size=25&page=1",
      "last": "https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page_size=25&page=3"
    }
  }
}

ステップ 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)
    • 発信先への各試行履歴
    • 開始、応答、終了のタイムスタンプ
    • 接続された通話の時間
    • 各通話試行の状況、および試行中に取得された通話結果 (call_outcomes) と変数 (call_attempts_variables)
    • 通話が転送された場合の転送情報: transfer_started_at、transfer_answered_at、および転送先 (transfer_destination)。通話が転送されなかった場合、これら 3 つはすべて null になります。
    • 該当する場合、エラーの詳細
  4. 通知 (call_notifications)
    • 通話に関連して送信された通知の状況
    • メッセージ数と配信状況
    • outbound_calls_notifications は非推奨です - call_notifications を使用してください。

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

{
  "uid": "d26a3041-1743-413f-9722-04ac1f612960",
  "external_id": "CUST-123",
  "status": "completed",
  "progress": "answered",
  "is_test_call": false,
  "cooldown_until": null,
  "delay": null,
  "priority": null,
  "retry_intervals": [300, 300, 300],
  "attempts_remaining": 0,
  "created_at": "2025-04-16T12:10:00Z",
  "updated_at": "2025-04-16T12:15:30Z",
  "outbound_call_info": {
    "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",
    "event_date_time": null,
    "external_id": "CUST-123",
    "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,
      "transfer_started_at": null,
      "transfer_answered_at": null,
      "transfer_destination": null,
      "call_outcomes": [
        {
          "uid": "6a938cdf-9b4b-4e8c-940b-05af78ea8666",
          "name": "APPOINTMENT_CONFIRMED",
          "created_at": "2025-04-16T12:15:00Z"
        }
      ],
      "call_attempts_variables": [
        {
          "uid": "e713afb6-b877-4c28-9809-07c0d93b6b31",
          "name": "Appointment time",
          "value": "3:30 PM",
          "status": "confirmed",
          "created_at": "2025-04-16T12:14:20Z"
        }
      ]
    }
  ],
  "call_notifications": [
    {
      "uid": "3f2a91d4-5c8e-4b17-9a63-0d1e7c45b2aa",
      "status": "delivered",
      "message_count": 1,
      "delivered_at": "2025-04-16T12:15:40Z"
    }
  ]
}