This document outlines the specific events one can subscribe to via a webhook.
Events are usually are composed of two parts: the event resource, and the event action. The "event resource" represents the kind of object that generated the event, while the "event action" represents the event's trigger. For example, for the event type intervention.assigned the event type is intervention and the event action is assigned.
Event Anatomy
Each event consists of three top-level elements. They are:
Property
Value
Description
id
String
Unique request identifier. This can be used to detect duplicated request, for example in case of failure.
domain_id
String
Unique domain identifier.
events
Array of Event object
An array of generated events.
You can see this structure in the following sample event notification triggered upon an assignation on an intervention:
Every webhook can contain multiple events. Each event then conforms to the following structure:
Property
Value
Description
type
String
The type of the event. Events MUST define this property. See "Event definition" below.
id
String
Unique event identifier. Events MUST define this property. This can be used to detect duplicate events in case of multiple send.
resource
Resource Object
It gives the resource of the event. Events MUST define this property.
issued_at
RFC-3339 date-time
The date and time at which the event happened. Events MUST define this property. This can be used to order the events client-side.
user_id
String
Unique user identifier. Will only appear for event triggered by an agent.
action
String
task.completed only, specifies the action leading to task completion, can be “deferred” or “closed”
Resource object
Each event is triggered by changes to a resource, e.g. a resource is created, updated, deleted, etc. That resource is described in a standard way, following the structure below:
Property
Value
Description
type
String
Type of resource. Resources MUST define this property. This gives information about the type of resource that must be queried from the API
id
Integer
Unique resource identifier. Resources MUST define this property.
metadata
Metadata Object
A resource MAY define some metadatas. The metadatas are additionals informations supplied to help by avoiding making extra queries to get them.
Available Events
The events are sorted by resource, the resource can be:
Interventions
Resource Types
Type
Description
intervention.assigned
When an agent is assigned to an intervention
intervention.canceled
When an agent cancels an intervention
intervention.closed
When an agent marks the intervention as closed
intervention.deferred
When an intervention is deferred for a period of time (the `intervention will be reactivated later)
intervention.opened
When an intervention is started by engaging a customer
intervention.reopened
When an intervention is reopened (by receiving a new message from the identity or manually by an agent, api ...)
intervention.custom_fields_updated
When custom fields of an intervention are updated
intervention.user_updated
When the agent of an intervention is changed (re-assigned)
intervention.reactivated
When an intervention deferred time is finished
intervention.recategorized
When categories on an intervention are changed
Metadata
Property
Value
Description
source_id
String
Unique identifier for the source (facebook, email...)
thread_id
String
Unique identifier for the thread
user_id
String
Unique identifier for the agent of an intervention
identity_id
String
Unique identifier for the identity which created the content
category_ids
Array
Array of unique identifier by categories
closed_at
String
The date when the intervention was closed
deferred_at
String
The date when the intervention was deferred
custom_field_values
Custom field Object
It gives the custom fields linked to the object
Tasks
Resource Types
Type
Description
task.assigned
When a new task is assigned to one or several agents
task.completed
When an agent marks a task as completed
task.created
When a task is created
task.destroyed
When contents are ignored or interventions are deferred or closed in folders view, related tasks are destroyed.
task.expired_from_step
When a task couldn't be delivered to any of the assigned agents for longer than the timeout defined for the topology step. It then continue to the next step.
task.expired_from_workbin
When a task was abandoned by an agent in his workbin automatically taken back by Engage Digital to be routed to other agents.
task.recategorized
When a content is recategorized, the task associated to this content gets the same categories.
task.resume
When an agent resumes handling of a task from his history or deferred tasks
task.supervisor_assigned
When a task is assigned to an agent by a supervisor and the option “Bypass queue and assign to agent” has been checked
task.taken
When an agent accepts a ringing task
task.transferred
When an agent or an administrator transfers a task to another agent
task.undelivered
When a task is moved into the undelivered queue
Metadata
Property
Value
Description
created_at
date-time
The date and time at which the task was created
channel_id
String
Unique identifier for the channel
source_id
String
Unique identifier for the source associated to the task's content
priority
Float
Priority of the task
content_id
String
Unique identifier for the content linked to the task
intervention_id
String
Unique identifier for the intervention linked to the task
agent_ids
Array
Array of unique identifier of agents assigned to the task
identity_id
String
Unique identifier of the content's author identity
action
String
task.completed only, specifies the action leading to task completion, can be “deferred” or “closed”
queue
String
Task’s current workbin
thread_id
String
Unique identifier for the thread linked to the task
type
String
task.taken only, specifies if the agent requested a task or took a ringing one. Can be “ring” or “request”
language
String
Language of the task's content
segment_index
Integer
Number starting at 1 and incremented each time a task is closed, defered or moved to another agent's workbin.
Push Agents
Resource Types
Type
Description
push_agent.accept_task
When an agent accepts a ringing task
push_agent.availability_change
When an agent's status changes
push_agent.busyness_change
When an agent’s busyness changes (according to the number of tasks in their workbin)
push_agent.connected
When an agent arrives on the push view
push_agent.disconnected
When an agent leaves the push view
push_agent.reconnected
When an agent reconnects after a network issue
push_agent.request_task
When an agent is busy but hasn’t reached the hard capability and requests an additional task
Metadata
Property
Value
Description
channels
Array
Array containing data for each channel in push mode. Each channel has the following properties
id
String
Unique identifier for the channel
name
String
Name of the channel
status
String
Status of the push_agent on the channel
busyness
String
Busyness of the push_agent on the channel
custom_status
Hash
Id of the custom_status used by the agent
Content
Resource Types
Type
Description
content.approved
When a content has been approved for publication. This does not mean that the content has been published yet. Notifications about exports are done with content.exported.
content.discussion_initiated
When a discussion has been started. This does not mean that the content has been published yet. Notifications about exports are done with content.exported.
content.exported
When a new content has been exported from Engage to the source. This does not mean that the export succeeded. The synchronization_status field needs to be checked.
content.imported
When a new content has been imported from the source to Engage.
content.replied
When someone replied to another content. This does not mean that the content has been published yet. Notifications about exports are done with content.exported.
content.update_exported
When a content has been update_exported (and the update has been propagated to the external source).
New content events
To be notified of new content from customers you should watch for content.imported but be careful as you will receive more than just customer contents.
In particular the content.imported event means imported from an Engage Digital point of view, it notifies all interactions coming directly from the synchronized source. For example you publish a post on a managed facebook page without using Engage Digital, a content.imported webhook will be triggered. For the Chat automatic welcome message (initial message) of the conversation will also be imported. So it’s not only customer message, this is a bit more complicated and some filtering may be required. To ignore those messages you will filter based on the status field to segregate actionable contents from customer vs. source itself.
Similarly, to be notified when a content has been exported from Engage Digital to the source, you should watch for content.exported (new content) which will also notify automatic messages like survey or auto response and content.update_exported for update on existing content.
Finally, if you need more granular or earlier notification about contents creation, you can subscribe to content.discussion_initiated (new discussion), content.replied (reply on a message) and content.approved (content has been approved).
It can be useful to understand the basic workflow of contents:
A new content is created from Engage Digital: it can trigger content.discussion_initiated if a new thread has been initiated by an agent (outgoing content). Otherwise, regular replies to contents triggers content.replied. Those content may not be exported yet depending on approval settings.
If the content requires to be approved (approval_required attribute is true), it has to wait for an approbation. Once the approbation is received, content.approved is triggered.
The content can now be exported to the external source. Successful and Unsuccessful export operations trigger the content.exported event for new contents, and content.update_exported event for existing events that have been edited.
Metadata
Property
Value
Description
id
String
ID of the content
approval_required
Boolean
Whether the content require approval before being published
author_id
String
ID of the author of the content
body
String
Body of the content
body_input_format
String
Format of the body (html, text)
created_from
String
From where the content has been created (interface, API, ...)
creator_id
String
ID of the creator of the content
date
String
Date at which the content was created
first_in_thread
Boolean
Whether the content is the first of the associated thread
foreign_categories
Array of Strings
Foreign categories associated to the content
foreign_id
String
ID of the content on the external website
has_attachment
Boolean
Whether the content has one or multiple attachments
intervention_id
String
ID of the intervention associated to the content
language
String
Language of the content
type
String
Type of the content
in_reply_to_author_id
String
ID of the author of the content for which this content is a reply
in_reply_to_id
String
ID of the content for which this content is a reply
private
Boolean
Whether the content is a private message
source_id
String
ID of the source associated to the content
source_type
String
Type of the source associated to the content
status
String
Status of the content
synchronization_status
String
For content.exported and content.update_exported event, the status of the synchronization (successful or unsuccessful).
thread_id
String
ID of the thread that owns the content
thread_title
String
Title of the thread that owns the content.
capabilities_supported
Array of Strings
List the types of structured messages that can be used to reply to this type of message.
Metadata
Identities
Resource Types
Type
Description
identity.merged
When an identity is merged to other identities.
identity.unmerged
When an identity is unmerged from other identities.
Metadata
Property
Value
Description
new_identity_group_id
String
ID of the new Identity Group attached to the identity after the merge/unmerge.
old_identity_group_id
String
ID of the Identity Group which was previously attached to the identity before the merge/unmerge.
Surveys
Resource Types
Type
Description
survey_response.imported
When a response to a survey has been imported.
Metadata
Property
Value
Description
submitted_at
date-time
Date/time response was submitted (EST/EDT or GMT -5/GMT -4)
main_indicator
Integer
Main question result
main_indicator_scaled
Float
Main question result scaled to 0..1
intervention_id
String
ID of the intervention related to this survey
survey_id
String
ID of the survey
source_id
String
ID of the source related to this survey
user_id
String
ID of the user related to this survey
questions
Array of Hashes
List of questions containing the displayed text of the question, its foreign_id (from the third party survey supplier) and their replies in the form of an Array. Each one of the replies entry contains two keys: text and value of the customer reply.
response_foreign_id
String
Internal Response ID fetched from the provider.
answers
Hash
[Deprecated] Please use questions instead. Survey question and responses
foreign_id
String
[Deprecated] Please use id instead. Internal Response ID generated by Engage Digital.
Custom Fields
Property
Value
Description
key
String
To have more information you need to look in Engage Digital custom field admin, it depends on your setup
value
String
To have more information you need to look in Engage Digital custom field admin, it depends on your setup