Menu

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?

REST API: Events

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 Instance Resource

Resource URI

/v1/Workspaces/{WorkspaceSid}/Events/{EventSid}

HTTP GET

This will return the specific event identified by {EventSid}.

Resource Properties

These are properties are associated with every Event.

Field Description
EventType An identifier for this event
AccountSid The account owning this event
Description A description of the event
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)
EventDate The time this event was sent (UTC time)
EventData Data about this specific event. See below for more information.

Event List Resource

Lists all the Events logged for each state change in the Workspace. See below for the contents of each Event. The contents will vary by Event type.

Resource URI

/v1/Workspaces/{WorkspaceSid}/Events

HTTP GET

You may add the following parameters for querying events.

Example

An example for listing events in a workspace

        
        
        
        
        Parameter Description
        Minutes Filter events by up to ‘x’ minutes in the past. This is helpful for events for the last 15 minutes, 240 minutes (4 hours), and 480 minutes (8 hours) to see trends. Defaults to 15 minutes.
        StartDate Filter events by a start date. This is helpful for defining a range of events to capture. Input is a GMT ISO 8601 Timestamp.
        EndDate Filter events by an end date. This is helpful for defining a range of events to capture. Input is a GMT ISO 8601 Timestamp.
        EventType Filter events by those of a certain event type
        WorkerSid Filter events by those pertaining to a particular worker
        TaskQueueSid Filter events by those pertaining to a particular queue
        TaskSid Filter events by those pertaining to a particular task
        ReservationSid Filter events by those pertaining to a particular reservation

        Note: By default, this will return the first 50 events. Supply a PageSize parameter to fetch more than 50 events. See paging for more information.

        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.

        Note: 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.

        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.
        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-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 enters a new queue during workflow processing
        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.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

        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
        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 browsing the Twilio tag on Stack Overflow.