# 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 |


## 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 |


### 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.