Webhook payloads

Every type of outbound webhook can contain different information according to the domain event that generated it, but all webhook types will adhere to the same general structure.

General webhook payload structure

Field	Type	Description
event_id	UUID string	id of the event
event_fqn	string	fully qualified name of the event (uppercase words separated by underscore, i.e. CONVERSATION_MESSAGE_ADDED)
event_version	string	version of the event
event_timestamp	timestamp	time when the event was emitted
organization	Organization object	organization that owns the event
data	Data object	type specific payload of the event

Data

Each type of webhook you can configure through the UI will have a different structure that contains information from the specific domain event that generated it. The type-specific structure will be as follows.

Created

A conversation is created inside Dixa

Field	Type	Description
conversation	Conversation object	conversation associated with the event

Open

A conversation is reopened (after it was closed).

Field	Type	Description
conversation	Conversation object	conversation associated with the event

Pending

A follow-up is added to a conversation, placing the conversation in pending status.

Field	Type	Description
conversation	Conversation object	conversation associated with the event

Pending expired

A follow-up added to the conversation has expired.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
pendingByUser	optional User object	agent who placed the conversation in pending state

Closed

A conversation IS closed.

Field	Type	Description
conversation	Conversation object	conversation associated with the event

Abandoned

A conversation is closed without an agent being assigned to it.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
queue	Queue object	queue of the conversation

Enqueued

A conversation enters a queue in Dixa.

Field	Type	Description
conversation	Conversation object	conversation associated with the event

Assigned

A conversation gets assigned to an agent.

Field	Type	Description
conversation	Conversation object	conversation associated with the event

Unassigned

A conversation gets unassigned from an agent.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
agent	User object	agent who was unassigned from this conversation

Note added

An internal note is added to a conversation.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
note_id	UUID string	id of the note
text	optional string	text content of the note
created_at	timestamp	time when the note was created
author	User object	agent who added the note

Message added

A message is added to the conversation.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
author	User object	user who authored the message
created_at	timestamp	time when the message was created
message_id	UUID string	id of the message
text	optional string	text content of the message
direction	string	direction of the message (inbound / outbound)¹
channel	string	channel of the conversation (uppercase channel name, i.e. EMAIL)
content	Content object	message content
attachments	optional array of Attachment objects	message attachments
external_id	optional string	id of the message in a third party system

Tag added

A tag is added to a conversation.

Field	Type	Description
conversation	Conversation	conversation associated with the event
tag	string	name of the tag
author	User object	agent who added the tag

Tag removed

A tag is removed from a conversation.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
tag	string	name of the tag
author	User object	agent who removed the tag

Rated

A conversation was rated by an enduser.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
agent	User object	agent assigned to the conversation
user	User object	user who rated the conversation
score	integer	rating score
comment	optional string	user comment
type	string	type of rating

Transcription Added

A conversation transcription was added.

Field	Type	Description
conversation	Conversation object	conversation associated with the event

Transferred to Agent

A conversation is transferred to an agent.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
transfer_id	UUID string	id of the transfer
initiator	User object	agent who initiated the transfer
type	string	type of transfer (BLIND, ASSISTED)
status	string	status of the transfer
destination	optional User object	target agent for the transfer
destination_type	String	type of transfer target

Transferred to Queue

A conversation is transferred to a queue.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
transfer_id	UUID string	id of the transfer
initiator	User object	agent who initiated the transfer
type	string	type of transfer (BLIND, ASSISTED)
status	string	status of the transfer
destination	optional Queue object	target queue for the transfer
destination_type	String	type of transfer target

Banned enduser

An enduser is banned.

Field	Type	Description
agent	User object	agent who banned the enduser
user	User object	enduser who was banned
reason	optional string	reason for banning the enduser
channels	array of string	channels from which enduser was banned (WIDGET_CHAT only)

Unbanned enduser

An enduser ban is removed.

Field	Type	Description
agent	User object	agent who unbanned the enduser
user	User object	enduser who was unbanned
reason	optional string	reason for unbanning the enduser
channels	array of string	channels from which enduser was unbanned (WIDGET_CHAT only)

Banned ip

An ip address is banned.

Field	Type	Description
agent	User object	agent who banned the ip address
ip_address	string	banned ip address
csid	integer	id of the conversation
reason	optional string	reason for banning the ip address

Unbanned ip

An ip address ban is removed.

Field	Type	Description
agent	User object	agent who unbanned the ip address
ip_address	string	unbanned ip address
csid	integer	id of the conversation
reason	optional string	reason for unbanning the ip address

End user replaced

The enduser for this conversation is updated as a result of a contact merge or because an anonymous contact was identified.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
author	User object	agent who replaced the enduser
old_user	User object	previous enduser
new_user	User object	current enduser
reason	string	reason for replacing the enduser

Custom Attribute Updated

Custom attributes of a conversation are updated.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
updated_attributes	array of CustomAttribute	list of updated custom attributes with new values
author	User object	agent who updated the custom attributes

Typing started

The agent is typing a message to the end user in Dixa's conversation view. The intention is to use the webhook to indicate agent activity to an end user.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
started_by_user_id	string	agent's id who started typing

SLA pending

An SLA evaluation is created for a conversation, awaiting outcome.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
sla_policy	SLA Policy object	SLA policy associated with the evaluation
previous_status	optional string	previous SLA evaluation status (uppercase words separated by underscore, i.e. `PENDING`)
status_changed_at	optional timestamp	time when the SLA evaluation status changed

SLA breached

A conversation has exceeded the SLA deadline.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
sla_policy	SLA Policy object	SLA policy associated with the evaluation
previous_status	optional string	previous SLA evaluation status (uppercase words separated by underscore, i.e. `PENDING`)
status_changed_at	optional timestamp	time when the SLA evaluation transitioned to breached
breached_at	optional timestamp	time when the SLA deadline was exceeded

SLA achieved

A conversation has met the SLA target.

Field	Type	Description
conversation	Conversation object	conversation associated with the event
sla_policy	SLA Policy object	SLA policy associated with the evaluation
previous_status	optional string	previous SLA evaluation status (uppercase words separated by underscore, i.e. `PENDING`)
status_changed_at	optional timestamp	time when the SLA evaluation transitioned to achieved
achieved_at	optional timestamp	time when the SLA target was met
breach_due_at	optional timestamp	time for SLA breach

SLA voided

An SLA evaluation is no longer applicable for a conversation (e.g. the conversation was transferred or conditions changed).

Field	Type	Description
conversation	Conversation object	conversation associated with the event
sla_policy	SLA Policy object	SLA policy associated with the evaluation
previous_status	optional string	previous SLA evaluation status (uppercase words separated by underscore, i.e. `PENDING`)
status_changed_at	optional timestamp	time when the SLA evaluation was voided

Payload objects

The type-specific event payloads can contain fields that are objects related to the event, such as an Organization, a User or a Conversation. The structure of these objects is as follows.

Organization

Field	Type	Description
id	UUID string	id of the organization
name	string	name of the organization

Conversation

Field	Type	Description
csid	UUID string	id of the conversation
channel	string	channel of the conversation (uppercase channel name, i.e. EMAIL)
status	string	status of the conversation (OPEN / CLOSED / PENDING / AWAITING_PENDING)
direction	string	direction of the conversation (INBOUND / OUTBOUND)¹
queue	optional Queue object	queue of the conversation
contact_point	optional string	contact point of the organization
requester	User object	enduser who requested the conversation
assignee	optional User object	agent assigned to the conversation
subject	optional string	subject of the conversation
tags	array of string	conversation tags
custom_attributes	array of CustomAttribute	custom attributes associated with the conversation
created_at	timestamp	time the conversation was created

Queue

Field	Type	Description
id	UUID string	id of the queue
name	string	name of the queue

SLA Policy

Field	Type	Description
id	integer	id of the SLA policy
name	string	name of the SLA policy
metric_type	string	dimension being measured (uppercase words separated by underscore, i.e. `RESPONSE_TIME`)
queue	optional Queue object	queue the SLA policy targets
channel	optional string	uppercase words separated by underscore, i.e. `FACEBOOK_MESSENGER`)

User

Field	Type	Description
id	UUID string	id of the user
name	optional string	name of the user
email	optional string	email of the user
phone	optional string	phone number of the user
user_type	string	one of Contact (end user), Member (agent/admin) or Bot
roles - deprecated, see user_type	array of string	user role/s
additional_emails	optional array of string	additional email addresses
additional_phone_numbers	optional array of string	additional e164 format phone numbers

Content

Field	Type	Description
text	optional string	text content of the message
content_type	string	type of the content: `Text`, `Html` or `Markdown`
original_content_url	string	url of the original message content
processed_content_url	string	url of the processed message content

CustomAttribute

Custom attributes can be of different types, each with their own value structure.

Common Fields (for all attribute types)

Field	Type	Required	Description
type	string	Yes	Type of the attribute. One of: `string`, `string_list`
label	string	No	Human-readable label for the attribute
value	See below	Yes	The attribute's value (structure depends on the attribute type)

String Attribute

Field	Type	Required	Description	Example
type	string	Yes	Must be `string`	`string`
value	string	Yes	The string value	`"text value"`

String List Attribute

Field	Type	Required	Description	Example
type	string	Yes	Must be `string_list`	`string_list`
value	array	Yes	Array of strings	`["list", "of", "strings"]`

Attachment

Field	Type	Description
url	string	url of the attachment
pretty_name	string	short name of the attachment

¹ Be aware that the value of the direction field are lower case in the message payload, and upper case in the conversation payload.

Webhook payloadsCopy Anchor Link

General webhook payload structureCopy Anchor Link

DataCopy Anchor Link

CreatedCopy Anchor Link

OpenCopy Anchor Link

PendingCopy Anchor Link

Pending expiredCopy Anchor Link

ClosedCopy Anchor Link

AbandonedCopy Anchor Link

EnqueuedCopy Anchor Link

AssignedCopy Anchor Link

UnassignedCopy Anchor Link

Note addedCopy Anchor Link

Message addedCopy Anchor Link

Tag addedCopy Anchor Link

Tag removedCopy Anchor Link

RatedCopy Anchor Link

Transcription AddedCopy Anchor Link

Transferred to AgentCopy Anchor Link

Transferred to QueueCopy Anchor Link

Banned enduserCopy Anchor Link

Unbanned enduserCopy Anchor Link

Banned ipCopy Anchor Link

Unbanned ipCopy Anchor Link

End user replacedCopy Anchor Link

Custom Attribute UpdatedCopy Anchor Link

Typing startedCopy Anchor Link

SLA pendingCopy Anchor Link

SLA breachedCopy Anchor Link

SLA achievedCopy Anchor Link

SLA voidedCopy Anchor Link

Payload objectsCopy Anchor Link

OrganizationCopy Anchor Link

ConversationCopy Anchor Link

QueueCopy Anchor Link

SLA PolicyCopy Anchor Link

UserCopy Anchor Link

ContentCopy Anchor Link

CustomAttributeCopy Anchor Link

Common Fields (for all attribute types)Copy Anchor Link

String AttributeCopy Anchor Link

String List AttributeCopy Anchor Link

AttachmentCopy Anchor Link

On this page