Menu

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

Loading Code Sample...
      
      
          
          
          
          
        
      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.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 timed-out for the workflow 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.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

      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.

      Loading Code Sample...