Event Resource
TaskRouter logs Events for each state change in the Workspace for the purpose of historical reporting and auditing. TaskRouter will also make an HTTP request containing the Event details to the Workspace's EventCallbackURL each time one these Events takes place (see Event callbacks for more information.)
Event properties
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account that created the Event resource. |
actor_sid
|
The SID of the resource that triggered the event. |
actor_type
|
The type of resource that triggered the event. |
actor_url
|
The absolute URL of the resource that triggered the event. |
description
|
A description of the event. |
event_data
|
Data about the event. For more information, see Event types. |
event_date
|
The time the event was sent, specified in ISO 8601 format. |
event_date_ms
|
The time the event was sent in milliseconds. |
event_type
|
The identifier for the event. |
resource_sid
|
The SID of the object the event is most relevant to, such as a TaskSid, ReservationSid, or a WorkerSid. |
resource_type
|
The type of object the event is most relevant to, such as a Task, Reservation, or a Worker). |
resource_url
|
The URL of the resource the event is most relevant to. |
sid
|
The unique string that we created to identify the Event resource. |
source
|
Where the Event originated. |
source_ip_address
|
The IP from which the Event originated. |
url
|
The absolute URL of the Event resource. |
workspace_sid
|
The SID of the Workspace that contains the Event. |
Fetch an Event resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Events/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Event to fetch. |
sid
Path
|
The SID of the Event resource to fetch. |
Example 1
List all Events
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Events
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Events to read. Returns only the Events that pertain to the specified Workspace. |
end_date
Optional
|
Only include Events that occurred on or before this date, specified in GMT as an ISO 8601 date-time. |
event_type
Optional
|
The type of Events to read. Returns only Events of the type specified. |
minutes
Optional
|
The period of events to read in minutes. Returns only Events that occurred since this many minutes in the past. The default is |
reservation_sid
Optional
|
The SID of the Reservation with the Events to read. Returns only Events that pertain to the specified Reservation. |
start_date
Optional
|
Only include Events from on or after this date and time, specified in ISO 8601 format. Task Attributes for Events older than 30 days will be redacted. |
task_queue_sid
Optional
|
The SID of the TaskQueue with the Events to read. Returns only the Events that pertain to the specified TaskQueue. |
task_sid
Optional
|
The SID of the Task with the Events to read. Returns only the Events that pertain to the specified Task. |
worker_sid
Optional
|
The SID of the Worker with the Events to read. Returns only the Events that pertain to the specified Worker. |
workflow_sid
Optional
|
The SID of the Workflow with the Events to read. Returns only the Events that pertain to the specified Workflow. |
task_channel
Optional
|
The TaskChannel with the Events to read. Returns only the Events that pertain to the specified TaskChannel. |
sid
Optional
|
The SID of the Event resource to read. |
Example 1
Example 2
If the StartDate of the Events request is greater than 30 days in the past, then the events returned will not contain fields that may contain Personally Identifiable Information. The fields labeled as PII in the tables below will be redacted.
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.
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.
| 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
The following are the events sent by TaskRouter. All relevant fields at that particular moment will be logged.
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. |
Task Events
| 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 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 |
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 |
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 |
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 |
Task 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 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. |
Worker 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 |
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 |
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.