Menu

TaskRouter Events Reference

TaskRouter will make an HTTP request containing Event details to the Workspace's EventCallbackURL each time an Event takes place. This page contains a full list of Events and a description of Event Callbacks.

A busy TaskRouter system will generate a large volume of Events at a frequent rate. Keep this in mind when considering how your application will scale.

Event Callbacks

The EventCallbackUrl is defined on the Workspace. Your application should respond to Event Callbacks with 204 No Content and a Content-Type header of application/json within 15 seconds.

TaskRouter will POST the following parameters to the EventCallbackURL configured on your Workspace each time an Event occurs.

Parameter Description
EventType An identifier for this event
AccountSid The account owning this event
WorkspaceSid The Workspace Sid generating this event
WorkspaceName The Workspace Name generating this event (📇 PII )
EventDescription A description of the event (📇 PII )
ResourceType The type of object this event is most relevant to (Task, Reservation, Worker)
ResourceSid The sid of the object this event is most relevant to (TaskSid, ReservationSid, WorkerSid)
Timestamp The time this event was sent

Event Types

Reservation

Events

EventType Field Data Description
reservation.created Task
Worker
TaskQueueSid
ReservationSid
WorkflowSid
A task is assigned to a worker
reservation.accepted Task
Worker
TaskQueueSid
ReservationSid
WorkflowSid
A task reservation is accepted by a worker
reservation.rejected Task
Worker
TaskQueueSid
ReservationSid
WorkflowSid
A task reservation is rejected by a worker
reservation.timeout Task
Worker
TaskQueueSid
ReservationSid
WorkflowSid
Too much time passed without a task being accepted or rejected. The reservation is canceled.
reservation.canceled Task
Worker
TaskQueueSid
ReservationSid
WorkflowSid
A task reservation is canceled before it has been accepted by a worker
reservation.rescinded Task
Worker
TaskQueueSid
ReservationSid
WorkflowSid
Multi-reservation was used for a task and another worker has accepted one of the created reservations
reservation.completed Task
Worker
TaskQueueSid
ReservationSid
WorkflowSid
A task reservation is completed. Aligns with task.completed.
reservation.failed Task
TaskQueueSid
ReservationSid
WorkflowSid
The reservation failed and was not assigned to an agent.
reservation.wrapup Task
Worker
TaskQueueSid
ReservationSid
WorkflowSid
The task reservation is being wrapped up by the agent; happens directly before task completion.

Task

Event

EventType Field Data Description
task.created Task
WorkflowSid
A task item is added to a Workspace
task.updated Task
TaskQueueSid
WorkflowSid
A task’s attributes are changed
task.canceled Task
TaskQueueSid
WorkflowSid
A task is canceled
task.wrapup Task
TaskQueueSid
WorkflowSid
A task is moved to wrapup state.
task.completed Task
TaskQueueSid
WorkflowSid
A task is completed
task.deleted Task
TaskQueueSid
WorkflowSid
A task is deleted via API. Does not include auto-deleted Tasks after cancelation/completion.
task.system-deleted Task
TaskQueueSid
WorkflowSid
A task is deleted via the system, after the task reaches its TTL.
task.transfer-initiated Task
TaskQueueSid
WorkflowSid
task.transfer-attempt-failed Task
TaskQueueSid
WorkflowSid
task.transfer-failed Task
TaskQueueSid
WorkflowSid
task.transfer-canceled Task
TaskQueueSid
WorkflowSid
task.transfer-completed Task
TaskQueueSid
WorkflowSid

Event Fields

When an event involving a Task is logged, the event callback will include the following fields.

Parameter Description
TaskSid The SID of the task that changed
TaskAttributes The JSON Attributes of the task (📇 PII )
TaskAge The age of the task
TaskPriority The priority of the task
TaskAssignmentStatus The assignment status of the task
TaskCanceledReason The reason that task was canceled
TaskCompletedReason The reason that task was completed

Task Channel

Events

EventType Field Data Description
task-channel.created TaskChannel A task channel is created
task-channel.updated TaskChannel A task channel is updated
task-channel.deleted TaskChannel A task channel is deleted

Event Fields

When an event comes in that relates to a Task Channel, the following fields will be passed in:

Parameter Description
TaskChannelSid The SID of the task-channel
TaskChannelName The Friendly Name of the task-channel (📇 PII )
TaskChannelUniqueName An application-defined string that uniquely identifies the Task Channel, such as voice or sms
TaskChannelOptimizedRouting Whether the Task Channel should prioritize Workers that have been idle. If true, Workers that have been idle the longest are prioritized.

Task Queue

Events

EventType Field Data Description
task-queue.created TaskQueueSid
TaskQueueName
TaskQueueTargetExpression
A TaskQueue has been created
task-queue.deleted TaskQueueSid
TaskQueueName
TaskQueueTargetExpression
A TaskQueue has been deleted
task-queue.entered Task
TaskQueueSid
WorkflowSid
A task enters its first queue during workflow processing
task-queue.timeout Task
TaskQueueSid
WorkflowSid
A workflow routing step timed-out and a task is leaving a queue
task-queue.moved Task
TaskQueueSid
WorkflowSid
A task leaves its current queue to move to a new queue during workflow processing
task-queue.expression.updated TaskQueueSid
TaskQueueTargetExpression
The queue expression has been updated

Worker

Events

EventType Field Data Description
worker.created Worker A worker is created
worker.activity.update Worker A worker’s activity is updated
worker.attributes.update Worker A worker’s attributes are updated
worker.capacity.update Worker
Channel
A worker's channel's configured capacity has been updated
worker.channel.availability.update Worker
Channel
A worker's channel's availability has been updated
worker.deleted Worker A worker is deleted

Event Fields

When an event comes in that relates to a Worker, the following fields will be passed in:

Parameter Description
WorkerSid The SID of the worker that changed
WorkerName The Friendly Name of the worker (📇 PII )
WorkerAttributes The JSON Attributes of the worker (📇 PII )
WorkerActivitySid The new activity sid of the worker
WorkerActivityName The new activity friendly name of the worker
WorkerVersion The current worker version

When an event comes in that relates to a Worker's activity changing, the following additional fields will be passed in:

Parameter Description
WorkerTimeInPreviousActivity The time spent in the previous activity, in seconds; truncated to zero decimals
WorkerTimeInPreviousActivityMs The time spent in previous activity , in milliseconds
WorkerPreviousActivitySid The previous activity sid prior to this state change

When an event comes in that relates to a Worker's configured channel capacity or availability changing, the following additional fields will be passed in:

Parameter Description
WorkerChannelAvailable The availability of the channel
WorkerChannelAvailableCapacity The available capacity of the channel
WorkerChannelPreviousCapacity The previous capacity of the channel
TaskChannelSid The associated channel sid
TaskChannelUniqueName The associated channel unique name
WorkerChannelTaskCount The number of assigned tasks to this worker on this channel

Workflow

Events

EventType Field Data Description
workflow.target-matched Task
WorkflowSid
A task item matches a workflow routing step
workflow.entered Task
WorkflowSid
A task enters a workflow
workflow.timeout Task
WorkflowSid
A task reaches the end of a workflow without being accepted and is removed from the workspace
workflow.skipped Task
WorkflowSid
A task skips-out of the workflow (because of skip_if in the final step) and is removed from the workspace
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

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

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more