Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

メニュー

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

TaskのWorkerへの割り当て:割り当てコールバックの処理

TaskRouterは、Taskを処理するWorkerを選択すると、アプリケーションサーバーにHTTPリクエストを送信します。 この割り当てコールバックの処理は、TaskRouterアプリケーションを作成する際の重要な要素です。

割り当てコールバックの概要

TaskRouterがワーカーを選択すると、次の処理が実行されます。

  1. タスクの割り当てステータスが 'reserved' に設定されます。
  2. Reservationインスタンスが生成され、選択されたWorkerとTaskがリンクされます。TaskRouterはTask Reservationタイマー(時間は設定可能。既定では120秒)を開始します。
  3. 同時にReservationが作成され、WebhookのPOSTリクエストがWorkflowの AssignmentCallbackURL に送信されます。このコールバックには、Task、選択されたWorker、Reservationそれぞれの詳細が含まれます。
  4. TaskRouterのJavaScriptライブラリを使用している場合、選択されたWorkerがWebSocket通知を受信して、そこに詳細が含まれているTaskによって予約されたことが通知されます。
  5. Eventコールバックが、WorkspaceのEventCallbackURLに送信されます。このコールバックには、 Task、選択されたWorker、Reservationそれぞれの詳細が含まれます。このコールバックは、TaskRouter環境での変更をログに記録する目的で使用されます。

Reservationが受諾(WorkerがTaskを受諾したことが確定する)または拒否(Workerが明示的にTaskを拒否したことを示す)されるか、またはタイムアウト(構成されている時間内に応答を受信しなかった)になるまで、そのステータスは 'pending' です。

割り当てプロセスを完了するには、アプリケーションで次の 2 つを実行する必要があります。

  1. TaskをWorkerに配信します
  2. Taskが承諾または拒否されたことを受信確認します。

では、アプリケーションでこれらの義務を果たすためのオプションについて、1 つずつ説明します。

Task割り当てコールバックのパラメーター

アプリケーションサーバーに送信される割り当てコールバック HTTP POST リクエストには、次のパラメーターが含まれます。

パラメーター 概要
Timestamp Task割り当てが行われた日時です
AccountSid Twilio の AccountSid です。
WorkspaceSid このWorkerとTaskのWorkspaceのIDです
WorkflowSid このTaskのルーティングを処理するWorkflowのIDです。
TaskQueueSid このTaskが割り当てられたときのQueueのIDです。
WorkerSid Taskが割り当てられたWorkerのIDです。
WorkerAttributes Workerを記述するJSON属性です。 例: { 'agent_id':'123456', 'phone':'+1558675309' }
TaskSid 割り当てられているTaskのIDです
TaskAttributes Taskに設定されているJSON属性です。例: { "type":"support_request", "account_number":"1234567"}
TaskAge 割り当て時のTaskの有効期限です
TaskPriority 割り当て時のTaskの優先度です
ReservationSid TaskをWorkerに一致させるReservationのIDです。

割り込みコールバックへの応答

アプリケーションは、次のいずれかの方法で割り当てコールバックに応答できます。

  1. 任意のアクションを実行して手動でReservationを承諾または拒否する
  2. ただちにTask Reservationを承諾する
  3. ただちにTask Reservationを拒否する
  4. 待機中の通話を TwiML Queueから外す
  5. 新しい発信通話を開始する
  6. アクティブな通話を新しい TwiML ドキュメントにリダイレクトする

注:割り当て命令(#2-6)の実行中に発生したエラーは、「Monitor」 -> 「Alerts」を指定することで、アカウントポータルに表示されます。

命令で応答する場合は、Content-Type ヘッダーは「application/json」で、本文は最低限「instruction」キーが含まれる有効な JSON オブジェクトでなければなりません。アプリケーションは、次のいずれかの方法で割り当てコールバックに応答できます。

重要: 開発者のアプリケーションが5秒以内に200 OKのHTTPレスポンスコードと「application/json」のContent-Typeヘッダーを伴うレスポンスを返さない場合、TaskRouterはAssignment Instructionレスポンスを処理せず、FallbackAssignmentCallbackUrlへの新規Webhookを開始します。

手動でReservationを承諾または拒否する

TaskRouterがTaskを処理するWorkerを予約した場合、アプリケーションは、割り当てを承諾または拒否する前に、おそらく何らかの非同期アクションを実行する必要があるのが普通です。 たとえば、ユーザーにTaskを処理できることを確認するように要求したり、データベースやCRMのレコードを変更したり、他の何らかのアクションを実行したりする必要があるでしょう。

これが、アプリケーションが使用する必要があるモデルである場合、割り当てコールバックに200 OK HTTPレスポンスを返します。これにより、アプリケーションが割り当てコールバック HTTP リクエストを受信したときに、必要とされる任意のアクションを実行することができ、その後アプリケーションに送信された割り当てコールバックパラメーターで渡されるReservationリソースにPOSTを送信して ReservationStatus=accepted または ReservationStatus=rejected を渡すことによってReservationを受諾または拒否することができます。詳細については、Task Reservationサブリソースをご覧ください。

ただちにReservationを承諾する

TaskRouterが選択したWorkerをアプリケーションがただちに承諾して、何もアクションを実行しないようにする場合、次のように応答できます。

{
  "instruction": "accept"
}

これにより、WorkerによってTaskが「承諾された」と見なされます。 これは、TaskRouterが処理を完了し、このTaskに対してこれ以上何も操作を実行しないことを示します。

ただちにReservationを拒否する

"instruction":"accept" と同じように、"instruction":"reject" はReservationを更新して、Taskを拒否し、Queueに戻します。ReservationされていたWorkerの状態は、activity_sid パラメーターで指定されるActivityに更新されます。このTaskがWorkerにただちに再割り当てされるのを防ぐために、このActivityを「利用不可」なActivityに設定することを推奨します。

プロパティ 必須 概要
instruction はい この操作では "reject" に設定します。
activity_sid はい The ActivitySid you would like to set for the Reserved Worker. If no ActivitySid is provided, worker remains in the same activity.

"reject" JSON レスポンスの例:

{ 
  "instruction": "reject",
  "activity_sid": "WA12345678"
} 

待機中の通話を TwiML Queueから外す

"instruction":"dequeue" レスポンスを、TwiML音声通話のEnqueue動詞とDial動詞と組み合わせて使用します。 Enqueue動詞を使用すると、Taskが作成されて、音声通話が保留されます。 割り当ての際にdequeue命令が返されると、TaskRouterは渡された電話番号に発信通話を発信します。 通話に応答があると、Taskは保留から外されて、エージェントにブリッジされます。

リンクされた通話の捕捉

Dequeueインストラクションの発行に先立って、TaskRouterはTaskのTaskAttributeをworker_call_sidで更新し、指定されたWorkerへの発信通話用に作成されたCallSidが分かるようにしています。

そのため、TaskのTaskAttributesはcall_sidおよびworker_call_sidを含んでいます。 これ以降、task.completedなどといったそのTaskに関連したEventには同様にこの情報を持っています。

リンクされた通話の捕捉が必要な場合は、この情報を持つtask.completedEventをリッスンするか照会するようにしてください。

メモ: 「dequeue」割り当て命令は、Enqueue動詞により作成されたTaskにのみ作用します。 TaskRouterとTwiMLの統合の詳細については、こちらをご覧ください。

プロパティ 必須 概要
instruction はい この操作では "dequeue" に設定します。
to いいえ Workerの連絡先URIです。 電話番号またはクライアントIDです。 Workerの属性に「contact_uri」プロパティが含まれない場合は必須です。
from いいえ Workerへの通話の発信者ID。 これは認証済みのTwilio番号である必要があります。 これを最初の発信先番号にする必要がある場合は、サポートにご連絡ください。 Enqueue動詞を使用して作成されたTaskで「from」が指定されていない場合、発信者がダイヤルした「To」番号が、「dequeue」命令を実行する際に「from」番号として使用されます。
post_work_activity_sid いいえ 通話終了後にWorkerを移動するActivity SIDです。
record いいえ 'record' 属性は、通話の両方のレグを録音できます。"record-from-answer" に設定すると、応答からの通話を録音します。初期値は、通話を録音しない "do-not-record" です。RecordingUrl が、status_callback_url により送信されます。
Timeout いいえ 相手から応答がないと判断するまで、"contact_uri" に関連付けられている電話の呼び出し音を鳴らし続ける時間を、整数値(秒)で指定します。初期値は 60 秒です。最大値は 999 秒です。この値を 15 秒などの低い値に設定し、留守番電話やボイスメールにつながる前に電話を切ることができます。
status_callback_url いいえ 通話完了Event発生時にTwilioが非同期のWebhook GETリクエストを送信するURLです。 **メモ: TaskRouterは、「taskCallSid」パラメーターとして、このTaskを作成した通話のsidを送信します。 これは、Workerへの通話が失敗した場合に非常に役に立ちます。このとき、Queueから元の通話を削除して、留守番電話に送信するか、または別のWorkerグループにルーティングする新しいWorkflowとしてQueueに入れることができます。
status_callback_events いいえ TaskRouterは、Workerの通話が完了すると、status_callback_urlにWebhook Eventを生成します。 「initiated」、「ringing」、「answered」のいずれかの通話の進行状況EventでWebhookを受け取るには、この属性を使用し、Eventの一覧をカンマで区切って指定します。 たとえば、「status_callback_events=answered,completed」は、Workerが通話に応答した場合および通話が切断された場合にそれぞれWebhook Eventを生成します。

"dequeue" JSON レスポンスの例:

{
  "instruction": "dequeue",
  "to": "+14151112222",
  "from": "+18001231234",
  "post_work_activity_sid": "WA0123456789abcdef0123456789abcdef"  
}

「to」プロパティが指定されない場合、Twilioは通話をQueueから外してWorkerの「contact_uri」属性に接続します。 両方が指定されている場合、Workerの「contact_uri」属性よりも、割り当て命令の「to」プロパティーが優先されます。

Workerの「contact_url」属性を利用する「Dequeue」 割り当てインストラクションの例:

{
  "instruction": "dequeue",
  "from": "+18001231234",
  "post_work_activity_sid": "WA0123456789abcdef0123456789abcdef"  
}

Workerの属性:

{
  "contact_uri":"+14151112222"
}

メモ: SIPを使用している場合、Workerの属性は次のようになります。

{
  "contact_uri":"sip:someone@somedomain.com"
}

通話を開始する

"instruction":"call" レスポンスは、Task割り当てに応じてTwilioから発信音声通話を開始します。 これは、Taskが、チームの誰かによるコールバックリクエストを表す場合または発信通話を必要とする作業項目を表す場合に、役立ちます。 「accept」パラメーターを「true」に設定すると、通話を開始するときにReservationを「accepted」に設定できます。「false」に設定してReservationを保留中状態のままにする場合、後で手動でReservationを受諾または拒否する必要があります。

"instruction":"call" は、お客様に接続する前に、通話を受ける担当者にカスタムなメッセージを再生する必要があるシナリオで使うことができます。

Callインストラクションの発行に先立って、TaskRouterはTaskのTaskAttributeをworker_call_sidで更新し、指定されたWorkerへの発信通話用に作成されたCallSidが分かるようにしています。

"instruction":"call" JSON レスポンスには、次のパラメーターを含めることができます。

プロパティ 必須 概要
instruction はい この操作では "call" に設定します。
to いいえ Workerの連絡先URIです。 電話番号またはクライアントIDです。 Workerの属性に「contact_uri」プロパティが含まれない場合は必須です。
from はい 発信通話を発信する際に使用する発信者 ID です。
url はい 応答するWorkerのレグで実行する有効なTwiML URIです。
accept いいえ 「true」に設定されている場合、Reservationは受諾されます(accept 命令と同じ)。それ以外の場合、アプリケーションが後でTaskを受諾または拒否する必要があります。 既定値は false です。
record いいえ 'record' 属性は、通話の両方のレグを録音できます。"record-from-answer" に設定すると、応答からの通話を録音します。初期値は、通話を録音しない "do-not-record" です。RecordingUrl が、status_callback_url により送信されます。
Timeout いいえ 相手から応答がないと判断するまで、"contact_uri" に関連付けられている電話の呼び出し音を鳴らし続ける時間を、整数値(秒)で指定します。初期値は 60 秒です。最大値は 999 秒です。この値を 15 秒などの低い値に設定し、留守番電話やボイスメールにつながる前に電話を切ることができます。
status_callback_url いいえ 有効なステータスコールバック url です。

"call" JSON レスポンスの例:

{
  "instruction": "call",
  "to": "joey",
  "from": "+15558675309",
  "url": "http://example.com/agent_answer",   
  "status_callback_url":
    "http://example.com/agent_answer_status_callback"
}

この例は、Twilio から Twilio クライアントアドレス client:joey に、発信者 ID として +15558675309 を使用して、発信通話を開始します。エージェントが応答すると、Twilio は http://example.com/agent_answer から返される TwiML を実行します。 エージェントの通話が完了すると、Twilio は最終 HTTP リクエストを http://example.com/agent_answer_status_callback に送信します。

「to」プロパティが指定されない場合、TwilioはWorkerの「contact_uri」属性に発信通話を開始します。 両方が指定されている場合、Workerの「contact_uri」属性よりも、割り当て命令の「to」プロパティのほうが優先されます。

Workerの「contact_uri」属性を利用する「call」割り当て命令の例:

{
  "instruction": "call",
  "from": "+15558675309",
  "url": "http://example.com/agent_answer",   
  "status_callback_url":
    "http://example.com/agent_answer_status_callback"
}

Workerの属性:

{
  "contact_uri":"client:joey"
}

橋渡しされる前にWorkerの通話端でカスタムなTwiMLが必要な場合は、"instruction":"call" レスポンスを EnqueueおよびDialのTwiML音声通話動詞と一緒に使います。Enqueue TwiML動詞を使って、TaskがQueueに入れられた場合、上記の http://example.com/agent_answer TwiMLコールバックは以下のようになります。

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="woman">You are now connecting with a customer</Say>
    <Dial record="true">
        <Queue reservationSid="YourReservationSid"/>
    </Dial>
</Response> 

これにより、Workerに再生されるメッセージが生成された後、通話がQueueから外されて、Workerへ橋渡しされ、通話が録音されます。

通話を新しい TwiML ドキュメントにリダイレクトする

"instruction":"redirect" は、POSTされたReservationを承諾し、指定された発信中の通話(callSid で識別)を新しいTwiML URLにリダイレクトします。 これは、Taskの通話を新しいIVRやカンファレンスに転送したり、その他Workerへの直接の橋渡しが望ましくないTwiMLシナリオの場合に役立ちます。 Taskの通話端でカスタムなTwiMLが必要な場合は、"instruction":"redirect" レスポンスを Enqueue およびDialのTwiML音声通話動詞と一緒に使います。

プロパティ 必須 概要
instruction はい この操作では "redirect" に設定します。
call_sid はい Queueに登録された(Enqueueによってなど)通話の Twilio 通話 SID。
url はい 通話をリダイレクトする有効な TwiML URI です。
accept いいえ ブール値です。 "true" に設定されている場合、Reservationは承諾されます。それ以外の場合、アプリケーションが後でTaskを受諾または拒否する必要があります。 既定値は false です。

'redirect' JSON レスポンスの例

{
  "instruction": "redirect",
  "call_sid": "CA123456789",
  "url": "http://example.com/assignment_redirect",
}

上記のレスポンス例では、http://example.com/assignment_redirect から取得した TwiML ドキュメントを使い、Reservationを承諾し、CallSid CA12346789 で通話をリダイレクトします。これにより、Twilio クライアントにダイヤルできます。

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Client>joey</Client>
    </Dial>
</Response>

また、ReservationSidに基づき、新しいカンファレンスにダイヤルし、ひとりまたは複数のWorkerに橋渡しすることもできます(例: エスカレーションシナリオ)。

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="woman">Thank you for your patience. You are now connecting with an agent</Say>
    <Dial>
        <Conference endConferenceOnExit="true">YourReservationSid</Conference>
    </Dial>
</Response>

リダイレクトを使うもう 1 つのシナリオ

通話命令を使うことで、通話が橋渡しされる前に、カスタムなメッセージを担当者に提供することができました。ただし、同じエクスペリエンスをお客様にも提供する場合、つまり担当者に通話を橋渡しする前にカスタムなメッセージをお客様に再生する場合は、"instruction":"redirect" を使うことができます。

基本的なフローは以下のようになります:

  1. ReservationSidで指定されたカンファレンスでWorkerにダイヤルします。 これは、割り当てコールバックで行うことができます。

  2. リダイレクト割り当て命令を使って、Queueから ReservationSid で指定されたカンファレンスにお客様を移行させます。

Rate this page:

ヘルプが必要ですか?

誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。