# 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](#organization) object | organization that owns the event | | data | [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](#conversation) object | conversation associated with the event | ### Open A conversation is reopened (after it was closed). | Field | Type | Description | | --- | --- | --- | | conversation | [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](#conversation) object | conversation associated with the event | ### Pending expired A follow-up added to the conversation has expired. | Field | Type | Description | | --- | --- | --- | | conversation | [Conversation](#conversation) object | conversation associated with the event | | pendingByUser | optional [User](#user) object | agent who placed the conversation in pending state | ### Closed A conversation IS closed. | Field | Type | Description | | --- | --- | --- | | conversation | [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](#conversation) object | conversation associated with the event | | queue | [Queue](#queue) object | queue of the conversation | ### Enqueued A conversation enters a queue in Dixa. | Field | Type | Description | | --- | --- | --- | | conversation | [Conversation](#conversation) object | conversation associated with the event | ### Assigned A conversation gets assigned to an agent. | Field | Type | Description | | --- | --- | --- | | conversation | [Conversation](#conversation) object | conversation associated with the event | ### Unassigned A conversation gets unassigned from an agent. | Field | Type | Description | | --- | --- | --- | | conversation | [Conversation](#conversation) object | conversation associated with the event | | agent | [User](#user) object | agent who was unassigned from this conversation | ### Note added An internal note is added to a conversation. | Field | Type | Description | | --- | --- | --- | | conversation | [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](#user) object | agent who added the note | ### Message added A message is added to the conversation. | Field | Type | Description | | --- | --- | --- | | conversation | [Conversation](#conversation) object | conversation associated with the event | | author | [User](#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)1 | | channel | string | channel of the conversation (uppercase channel name, i.e. EMAIL) | | content | [Content](#content) object | message content | | attachments | optional array of [Attachment](#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) | conversation associated with the event | | tag | string | name of the tag | | author | [User](#user) object | agent who added the tag | ### Tag removed A tag is removed from a conversation. | Field | Type | Description | | --- | --- | --- | | conversation | [Conversation](#conversation) object | conversation associated with the event | | tag | string | name of the tag | | author | [User](#user) object | agent who removed the tag | ### Rated A conversation was rated by an enduser. | Field | Type | Description | | --- | --- | --- | | conversation | [Conversation](#conversation) object | conversation associated with the event | | agent | [User](#user) object | agent assigned to the conversation | | user | [User](#user) object | user who rated the conversation | | score | integer | rating score | | comment | optional string | user comment | | type | string | type of rating | ### Transferred to Agent A conversation is transferred to an agent. | Field | Type | Description | | --- | --- | --- | | conversation | [Conversation](#conversation) object | conversation associated with the event | | transfer_id | UUID string | id of the transfer | | initiator | [User](#user) object | agent who initiated the transfer | | type | string | type of transfer (BLIND, ASSISTED) | | status | string | status of the transfer | | destination | optional [User](#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](#conversation) object | conversation associated with the event | | transfer_id | UUID string | id of the transfer | | initiator | [User](#user) object | agent who initiated the transfer | | type | string | type of transfer (BLIND, ASSISTED) | | status | string | status of the transfer | | destination | optional [Queue](#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](#user) object | agent who banned the enduser | | user | [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](#user) object | agent who unbanned the enduser | | user | [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](#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](#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](#conversation) object | conversation associated with the event | | author | [User](#user) object | agent who replaced the enduser | | old_user | [User](#user) object | previous enduser | | new_user | [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](#conversation) object | conversation associated with the event | | updated_attributes | array of [CustomAttribute](#customattribute) | list of updated custom attributes with new values | | author | [User](#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](#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](#conversation) object | conversation associated with the event | | sla_policy | [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](#conversation) object | conversation associated with the event | | sla_policy | [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](#conversation) object | conversation associated with the event | | sla_policy | [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](#conversation) object | conversation associated with the event | | sla_policy | [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)1 | | queue | optional [Queue](#queue) object | queue of the conversation | | contact_point | optional string | contact point of the organization | | requester | [User](#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](#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](#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) | | 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 | 1 Be aware that the value of the direction field are lower case in the message payload, and upper case in the conversation payload.