### IsTeamOnline Event Payload Example

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Example JSON payload for the 'isTeamOnline' event type sent by the bot.

```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "isTeamOnline",
    "teamId": "team_abc"
  }
}
```

--------------------------------

### IsTeamOnline Event Response Example

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Example JSON response structure for the 'isTeamOnline' event, indicating team availability.

```json
{
  "isOnline": true
}
```

--------------------------------

### Escalate Event Payload Example

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Example JSON payload for the 'escalate' event type sent by the bot.

```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "escalate",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "escalateTo": "team_123"
  }
}
```

--------------------------------

### WidgetEscalate Event Payload Example

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Example JSON payload for the 'widgetEscalate' event. It includes the bot ID, event type, platform conversation ID, and an optional escalation target.

```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetEscalate",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "escalateTo": "string"
  }
}
```

--------------------------------

### Widget Message Payload Example

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

This is an example payload for a `widgetMessage` event, sent when a customer sends a message in an escalated widget conversation. It includes bot ID, event type, and conversation details.

```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "text": "Hello, this is a customer message in an escalated conversation"
  }
}
```

--------------------------------

### Widget Escalation Webhook Handler

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Example TypeScript handler for processing incoming webhook events from the Widget Escalation API.

```APIDOC
## POST /converse-webhook

### Description
Receives and processes various event types related to escalated conversations from the AI Agents Widget.

### Method
POST

### Endpoint
`/converse-webhook` (customizable)

### Request Body
- **botId** (string) - Required - The ID of the bot sending the event.
- **data.eventType** (string) - Required - The type of event (e.g., `widgetEscalate`, `widgetMessage`).
- **data.platformConversationId** (string) - Required - The external conversation ID.
- **data.conversationId** (string) - Required - The internal conversation ID (can be ignored).
- **data.escalateTo** (string) - Optional - CRM escalation team ID.

### Request Example
```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetEscalate",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "escalateTo": "string"
  }
}
```

### Response
#### Success Response (200 OK)
- No response body.

#### Error Response
- `4XX`–`5XX` (failure)
```

--------------------------------

### POST /converse/ticket Request Body Example

Source: https://developer.zendesk.com/api-reference/ai-agents/ticket/ticket

Use this JSON body to send an event to initiate or update a ticket conversation. Ensure all required fields like platformConversationId and platform are included. Metadata can be used to store session variables, with an option to sanitize PII.

```json
{
  "platformConversationId": "f15ee8b6-cf3e-4eaf-bf27-507ded70519a",
  "text": "I need to update my shipping address",
  "platform": "PUBLIC_API",
  "metaData": [
    {
      "key": "order_id",
      "value": "ABC123",
      "sanitize": true
    },
    {
      "key": "customer_id",
      "value": "user-9742"
    }
  ]
}
```

--------------------------------

### Widget End Session Payload Example

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

This is an example payload for a `widgetEndSession` event, triggered when a customer explicitly ends an escalated conversation using the Ultimate Chat Widget. It contains the bot ID and conversation identifiers.

```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetEndSession",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5"
  }
}
```

--------------------------------

### Get Signed URLs for Enhanced Data Export

Source: https://developer.zendesk.com/api-reference/ai-agents/data-export/data-export

Fetches downloadable (signed) URLs for enhanced Gen3 exported data on a specified date. Optionally specify a ttl value in minutes to define how long the signed URL remains valid.

```json
{
  "date": "2024-05-07",
  "ttl": 10
}
```

--------------------------------

### Get Signed URLs for Enhanced Data Export

Source: https://developer.zendesk.com/api-reference/ai-agents/data-export/data-export

Fetches downloadable (signed) URLs for enhanced Gen3 exported data on a specified date. The API responds with the requested date and a list of signed URLs for available export files. You can optionally specify a ttl value in minutes to define how long the signed URL remains valid.

```APIDOC
## POST /data-export/v3/get-signed-urls

### Description
Fetches downloadable (signed) URLs for enhanced Gen3 exported data on a specified date.

### Method
POST

### Endpoint
/data-export/v3/get-signed-urls

### Parameters
#### Header Parameters
- **authorization** (string) - Required - Your API authorization token
- **organizationid** (string) - Required - The id of the organization
- **botid** (string) - Required - The id of the bot for the export

#### Request Body
- **date** (string) - Required - The date for which data export is requested, in `YYYY-MM-DD` format
- **ttl** (integer) - Optional - The duration, in minutes, that the URL is valid and usable

### Request Example
```json
{
  "date": "2024-05-07",
  "ttl": 10
}
```

### Responses
#### Success Response (200)
The request was successful. Returns the requested date and a list of signed URLs for downloading export files.
- **date** (string) - The date for which data export was requested.
- **urls** (array) - A list of signed URLs for available export files.

#### Error Response (400)
Bad request. The request body is invalid or missing required fields.

#### Error Response (500)
Internal server error.
```

--------------------------------

### Example AI Agents Ticket API Webhook Payload

Source: https://developer.zendesk.com/api-reference/ai-agents/ticket/ticket-webhook

This JSON object represents a typical webhook event payload sent from the Ticket API, containing message details and predicted intents.

```json
{
  "botId": "618a30beee4e8e87d2f94015",
  "conversationId": "conversation1",
  "platformConversationId": "session1",
  "text": "Hello, this is a bot text message",
  "predictedIntents": [
    {
      "value": "1234",
      "name": "intent name",
      "confidence": 1
    }
  ],
  "attachments": [
    {
      "path": "path/to/attachment"
    }
  ]
}
```

--------------------------------

### Example Chat API Request Body

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat

This JSON object represents a conversation event sent to the Chat API. It includes a platform-specific conversation ID, the event type, message text, optional metadata with a sanitize flag, and a card index.

```json
{
  "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
  "eventType": "I want to request a refund",
  "text": "string",
  "metaData": {
    "key": "user_id",
    "value": "1234",
    "sanitize": true
  },
  "cardIndex": 0
}
```

--------------------------------

### Example Text Message Payload

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

This JSON payload represents a simple text message sent from the bot. It includes details such as botId, eventType, conversation IDs, message type, and the text content. Ensure your handler correctly parses these fields.

```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "sendMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "type": "text",
    "replyId": "REPLY_ID",
    "buttons": [],
    "text": "Hello, this is a bot text message",
    "carouselCards": [],
    "predictedIntents": [
      { "value": "1234", "name": "intent name", "confidence": 1 }
    ]
  }
}
```

--------------------------------

### Response handling

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Details the expected webhook responses for `sendMessage` events.

```APIDOC
## Response handling
A successful `sendMessage` will return a 200 response to the webhook request and no response body. A failed `sendMessage` will return a 4XX - 5XX range response to the webhook request.
```

--------------------------------

### Handling Webhook Events

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Webhooks are sent as POST requests to a specified endpoint (e.g., /converse-webhook). Your application should process each event asynchronously and respond with a 200 OK.

```APIDOC
## POST /converse-webhook

### Description
Receives asynchronous event notifications from the AI Agents Chat API.

### Method
POST

### Endpoint
/converse-webhook

### Request Body
- **eventType** (string) - The type of event (e.g., sendMessage, escalate, isTeamOnline).
- **data** (object) - Contains event-specific data.

### Response
#### Success Response (200)
An empty 200 OK response acknowledges receipt of the webhook.

### Example Handler (TypeScript)
```typescript
public processEvent = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
  const requestBody: ConverseWebhookDto = req.body;
  try {
    this.converseWebhookService.processConverseWebhookEvent(requestBody);
    res.status(200).send();
  } catch (error: any) {
    next(error);
  }
};
```
```

--------------------------------

### Send Button List Message

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Use this structure to send a message with a list of buttons for user selection. Ensure 'eventType' is 'sendMessage' and 'type' is 'text'.

```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "sendMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "type": "text",
    "replyId": "REPLY_ID",
    "buttons": [
      { "type": "button", "text": "YES" },
      { "type": "button", "text": "NO" }
    ],
    "text": "It's a bot text message with 2 buttons",
    "carouselCards": [],
    "predictedIntents": [
      { "value": "1234", "name": "intent name", "confidence": 1 }
    ]
  }
}
```

--------------------------------

### Process IsTeamOnline Webhook Event (TypeScript)

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Handles the IS_TEAM_ONLINE event from the bot. Your application should implement logic to check agent/team availability and respond with the status.

```typescript
/** * Processes the Converse Webhook event. * @param converseWebhookDto The event payload from the bot */public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {  switch (converseWebhookDto.data.eventType) {    case ConverseWebhookEventTypes.IS_TEAM_ONLINE:      /**       * Handles the event where the bot needs to check the availability of human agents.       * The payload for this event is defined in the BotIsTeamOnlineEvent class.       * Your application should process the request and respond with agent/team       * availability using the BotIsTeamOnlineEventResponse class.       */      logger.info(        `Received ${ConverseWebhookEventTypes.IS_TEAM_ONLINE} event: 
${JSON.stringify(          converseWebhookDto        )}`      );      // Add your availability-check logic here      break;    default:      break;  }}
```

--------------------------------

### widgetEscalate Event Processing

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Details on handling the `widgetEscalate` event, triggered when a bot escalates a conversation to a human agent.

```APIDOC
## widgetEscalate Event Details

### Description
This event occurs when the bot triggers an escalation to a human agent. The bot stops sending messages, and the conversation must be handled by your application.

### Payload
- **botId** (string) - Required - The ID of the bot sending the event.
- **data.eventType** (string) - Required - Set to `widgetEscalate`.
- **data.platformConversationId** (string) - Required - The conversation id (external).
- **data.conversationId** (string) - Required - Ultimate internal conversation id (can be ignored).
- **data.escalateTo** (string) - Optional - CRM escalation team id.

### Request Example
```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetEscalate",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "escalateTo": "string"
  }
}
```

### Response
- `200 OK` (success, no response body)
- `4XX`–`5XX` (failure)
```

--------------------------------

### Send escalation events to a widget

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation

Use this endpoint to send escalation updates or agent messages to an active widget session. The API acknowledges your request with a 200 OK and processes it asynchronously. The customer-facing widget is updated in real time as events are received.

```APIDOC
## POST /agent/converse/send-message-to-widget

### Description
Sends escalation updates or agent messages to an active widget session.

### Method
POST

### Endpoint
`https://api.ultimate.ai/agent/converse/send-message-to-widget`

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API key for the bot. Generate the key from the Custom CRM integration page in the Ultimate.ai dashboard. See the Authentication article for details.
- **botid** (string) - Required - The ID of the bot sending or receiving the event.

#### Request Body
- **platformConversationId** (string) - Yes - Unique identifier for the conversation, generated by the custom CRM application.
- **eventType** (string) - Yes - The type of escalation event. Possible values: "escalationQueueUpdate", "escalationSuccess", "message", "escalationFailed", "agentDisconnect"
- **text** (string) - No - Text content of the agent’s message (required if eventType is "message")
- **agent** (string) - No - Name of the agent if eventType is "escalationSuccess"
- **agentAvatar** (string) - No - URL for the agent’s avatar if eventType is "escalationSuccess"
- **queuePosition** (string) - No - Visitor’s position in the queue if eventType is "escalationSuccess"
- **waitingTime** (string) - No - Estimated wait time for the visitor in minutes if eventType is "escalationSuccess".

### Request Example
```json
{
  "platformConversationId": "123456789",
  "eventType": "escalationSuccess",
  "agent": "John Smith",
  "agentAvatar": "https://example.com/avatar/john-smith.png"
}
```

### Responses
#### Success Response (200)
The request has been acknowledged and will be processed. The actual response will be delivered through webhooks.

#### Error Responses
- **400** Bad request. The request body is invalid or missing required fields.
- **401** Unauthorized. Missing or invalid API key or bot ID.
- **404** Not found. The specified endpoint does not exist.
```

--------------------------------

### Converse with a Bot

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat

Sends an event to initiate or continue a conversation with a bot. The API acknowledges your message with a 200 OK and processes it asynchronously. Any response from the bot is delivered via your configured webhook.

```APIDOC
## POST /converse/chat

### Description
Sends an event to initiate or continue a conversation with a bot. The API acknowledges your message with a `200 OK` and processes it asynchronously. Any response from the bot is delivered via your configured webhook.

### Method
POST

### Endpoint
`/converse/chat`

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API key for the bot. Generate this from the Custom CRM integration page in the Ultimate.ai dashboard. For more information, see Authentication
- **botid** (string) - Required - The id of the bot sending or receiving the event

#### Request Body
- **platformConversationId** (string) - Required - Unique ID for the conversation, generated by your custom CRM application.
- **eventType** (string) - Required - Type of event. Possible values: "startSession", "message", "endSession", "metadata". See Event types
- **text** (string) - Optional - Message text from the visitor. Not used with "startSession" or "endSession". For button or carousel selection, send the button value as text unless it is a link button.
- **metaData** (object) - Optional - Metadata associated with the user or conversation session. This can be used for personalization or content.
  - **key** (string) - Required - Name of the session parameter
  - **value** (string) - Required - String value for the session parameter
  - **sanitize** (boolean) - Optional - Set to `true` for personally identifiable information (PII) data.
- **cardIndex** (number) - Optional - Index of the selected card from a carousel. Not used with `startSession` or `endSession`. Card indexes begin at 0

### Request Example
```json
{
  "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
  "eventType": "message",
  "text": "I want to request a refund",
  "metaData": {
    "key": "user_id",
    "value": "1234",
    "sanitize": true
  },
  "cardIndex": 0
}
```

### Response
#### Success Response (200)
The request has been acknowledge and will be processed. The actual response will come through webhooks.

#### Error Responses
- **400** - Bad request. The request body is invalid or missing required fields.
- **401** - Unauthorized. Missing or invalid API key or bot ID.
- **403** - Forbidden. AI Agent not using custom CRM.
- **404** - Not found. The specified endpoint does not exist.
```

--------------------------------

### Process Escalation Webhook Event (TypeScript)

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Handles the ESCALATE event from the bot. This event is processed synchronously, and the response indicates success or failure.

```typescript
/**  * This method processes the Converse Webhook event.  * @param converseWebhookDto  */  public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {    switch (converseWebhookDto.data.eventType) {      case ConverseWebhookEventTypes.ESCALATE:        /**          * This event represents an escalation request from the bot.          *          * The payload of this event is represented in the BotEscalationEvent class.          *          * The request will be processed SYNCHRONOUSLY and respond if the escalation was successful (200) or not (4xx-5xx).          */        logger.info(          Received ${ConverseWebhookEventTypes.ESCALATE} event: 
 ${JSON.stringify(converseWebhookDto)}`        );        break;      default:        break;    }  }}
```

--------------------------------

### Converse with a Ticket Automation Agent

Source: https://developer.zendesk.com/api-reference/ai-agents/ticket/ticket

Sends an event to initiate or update a ticket conversation. The API acknowledges your message with a 200 OK and processes it asynchronously. Any response from the virtual agent will be delivered via your configured webhook.

```APIDOC
## POST /converse/ticket

### Description
Sends an event to initiate or update a ticket conversation. The API acknowledges your message with a `200 OK` and processes it asynchronously. Any response from the virtual agent will be delivered via your configured webhook.

### Method
POST

### Endpoint
/converse/ticket

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API key for the bot. Generate the key from the Custom CRM integration page in the Ultimate.ai dashboard. See the Authentication article for details.
- **botid** (string) - Required - The ID of the bot sending or receiving the event.

### Request Body
- **platformConversationId** (string) - Required - Unique ID for the conversation, generated by the custom CRM application.
- **text** (string) - Optional - The text content of the ticket update or message.
- **platform** (string) - Required - Name of the platform sending the request. For custom CRM applications, use "PUBLIC_API".
- **metaData** (array) - Optional - Metadata variables to store in the session.
  - **key** (string) - Required - The variable or session parameter name.
  - **value** (string) - Required - The value for the variable. Only string values are supported.
  - **sanitize** (boolean) - Optional - Set to `true` for personally identifiable information (PII) data.

### Request Example
```json
{
  "platformConversationId": "f15ee8b6-cf3e-4eaf-bf27-507ded70519a",
  "text": "I need to update my shipping address",
  "platform": "PUBLIC_API",
  "metaData": [
    {
      "key": "order_id",
      "value": "ABC123",
      "sanitize": true
    },
    {
      "key": "customer_id",
      "value": "user-9742"
    }
  ]
}
```

### Responses
#### Success Response (200)
The request has been acknowledged and will be processed. The actual response will be delivered through webhooks.

#### Error Responses
- **400** Bad request. The request body is invalid or missing required fields.
- **401** Unauthorized. Missing or invalid API key or bot ID.
- **403** Forbidden. AI Agent not using custom CRM.
- **404** Not found. The specified endpoint does not exist.
- **500** Internal server error.
```

--------------------------------

### Send Escalation Event to Widget

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation

Use this endpoint to send escalation updates or agent messages to an active widget session. The API acknowledges the request with a 200 OK and processes it asynchronously, updating the customer-facing widget in real time.

```json
{
  "platformConversationId": "123456789",
  "eventType": "escalationSuccess",
  "agent": "John Smith",
  "agentAvatar": "https://example.com/avatar/john-smith.png"
}
```

--------------------------------

### Button list message

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Represents a message from the bot containing a list of buttons for user selection. The `data.type` should be set to `text` for this message type.

```APIDOC
## Button list message
A message from the bot containing a list of buttons the user can select.

### Fields
- **botId** (string): The id of the bot sending the event
- **data.eventType** (string): Set to `sendMessage`
- **data.platformConversationId** (string): Conversation id (external)
- **data.conversationId** (string): (Optional) Internal conversation id
- **data.type** (string): Set to `text` for a button list message
- **data.replyId** (string): The reply id that triggered this message
- **data.text** (string): Optional. Main message text (can be omitted)
- **data.buttons** (array): Array of button objects. See Button object
- **data.carouselCards** (array): Always empty for a button list message
- **data.predictedIntents** (array): Array of predicted intent objects. Each object must contain:
    - value: string (intent id)
    - name: string (intent name)
    - confidence: number (confidence score, 0–1)

#### Button object
- **type** (string): Must be "button"
- **text** (string): The button display text

### Example
```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "sendMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "type": "text",
    "replyId": "REPLY_ID",
    "buttons": [
      { "type": "button", "text": "YES" },
      { "type": "button", "text": "NO" }
    ],
    "text": "It's a bot text message with 2 buttons",
    "carouselCards": [],
    "predictedIntents": [
      { "value": "1234", "name": "intent name", "confidence": 1 }
    ]
  }
}
```
```

--------------------------------

### Process Incoming Webhook Events (TypeScript)

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Handles incoming webhook events from the Widget Escalation API. It processes the request body and delegates event processing to a service. Errors are caught and passed to the next middleware.

```typescript
/** * Processes incoming webhook events from the Widget Escalation API. * @param req * @param res * @param next */public processEvent = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
  const requestBody: ConverseWebhookDto = req.body;
  try {
    this.converseWebhookService.processConverseWebhookEvent(requestBody);
    res.status(200).send();
  } catch (error: any) {
    next(error);
  }
};
```

--------------------------------

### Process IsTeamOnline Event

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Handles the `isTeamOnline` event type from the Converse Webhook. This event is sent when the bot needs to check if a specific support team or agent group is available. Your webhook should handle this event synchronously and respond with a boolean value indicating availability.

```APIDOC
## IS_TEAM_ONLINE Webhook Event

### Description
The `isTeamOnline` event is sent when the bot needs to check if a specific support team or agent group is available. Your webhook should handle this event synchronously and respond with a boolean value indicating whether the requested team is online.

### Payload Structure
- **botId** (string) - The id of the bot sending the event
- **data.eventType** (string) - Set to `isTeamOnline`
- **data.conversationId** (string) - (Optional) Internal conversation id
- **data.teamId** (string) - (Optional) The team id to check for availability

### Request Example
```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "isTeamOnline",
    "teamId": "team_abc"
  }
}
```

### Response Structure
- **isOnline** (boolean) - Returns `true` if the team is available, `false` otherwise.

### Response Example
```json
{
  "isOnline": true
}
```
```

--------------------------------

### Process Escalation Event

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Handles the `escalate` event type from the Converse Webhook. This event signifies a request to escalate the conversation, and it is processed synchronously. A successful escalation returns a 200 OK, while failures return appropriate error codes.

```APIDOC
## ESCALATE Webhook Event

### Description
This event represents an escalation request from the bot. The payload is represented in the `BotEscalationEvent` class. The request will be processed SYNCHRONOUSLY and respond if the escalation was successful (200) or not (4xx-5xx).

### Payload Structure
- **botId** (string) - The id of the bot sending the event
- **data.eventType** (string) - Set to `escalate`
- **data.platformConversationId** (string) - The external conversation id
- **data.conversationId** (string) - (Optional) Internal conversation id
- **data.escalateTo** (string) - (Optional) The escalation team’s CRM id

### Request Example
```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "escalate",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "escalateTo": "team_123"
  }
}
```

### Response
- **Success Response (200)**: No response body.
- **Error Response**: Appropriate `4XX` or `5XX` error code.
```

--------------------------------

### Widget Message Event

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Handles incoming messages from the widget during an escalated conversation.

```APIDOC
## POST /webhooks/widget-escalation

### Description
This endpoint receives messages from the widget when a conversation is escalated.

### Method
POST

### Endpoint
/webhooks/widget-escalation

### Request Body
- **botId** (string) - Required - The id of the bot sending the event
- **data** (object) - Required
  - **eventType** (string) - Required - "widgetMessage"
  - **platformConversationId** (string) - Required - The conversation id (external)
  - **conversationId** (string) - Required - Ultimate internal conversation id (can be ignored)
  - **text** (string) - Required - The message text

### Request Example
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "text": "Hello, this is a customer message in an escalated conversation"
  }
}

### Response
#### Success Response (200 OK)
No response body.
```

--------------------------------

### Process Converse Webhook Event - widgetEscalate (TypeScript)

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Processes the Converse Webhook event, specifically handling the 'widgetEscalate' event type. This event signifies an escalation request from a bot using the Ultimate Chat Widget. The event is logged and processed asynchronously.

```typescript
/**     * This method processes the Converse Webhook event.     * @param converseWebhookDto     */    public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
        switch (converseWebhookDto.data.eventType) {
            case ConverseWebhookEventTypes.WIDGET_ESCALATE:
                /**                 * This event represents an escalation request from the bot for customers who are using Ultimate Chat Widget                 *                 * The payload of this event is represented in the BotWidgetMessageEvent class.                 *                 * The request will be acknowledged and then processed ASYNCHRONOUSLY.                 */                logger.info(
                    `Received ${ConverseWebhookEventTypes.WIDGET_ESCALATE} event: \n ${JSON.stringify(
                        converseWebhookDto
                    )}`
                );
                break;
            default:
                break;
        }
    }}
```

--------------------------------

### Process Converse Webhook Event Method

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

A TypeScript method to process incoming Converse Webhook events. It includes a switch statement to handle different event types, specifically logging the `WIDGET_END_SESSION` event.

```typescript
/**     * This method processes the Converse Webhook event.     * @param converseWebhookDto     */    public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
        switch (converseWebhookDto.data.eventType) {
            case ConverseWebhookEventTypes.WIDGET_END_SESSION:
                /**                 * This event represents an end escalated session request from the user to an agent in an escalated conversation                 * for customers that are using Ultimate Chat Widget                 *                 * The payload of this event is represented in the BotWidgetEndSessionEvent class.                 *                 * The request will be acknowledged and then processed ASYNCHRONOUSLY.                 */                logger.info(
                    `Received ${ConverseWebhookEventTypes.WIDGET_END_SESSION} event: \n ${JSON.stringify(
                        converseWebhookDto
                    )}`
                );
                break;
            default:
                break;
        }
    }}
```

--------------------------------

### widgetMessage Event Processing

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Details on handling the `widgetMessage` event, triggered when a customer sends a message during an escalated conversation.

```APIDOC
## widgetMessage Event Details

### Description
This event occurs when a customer sends a message to an agent during an escalated conversation using the Ultimate Chat Widget. Your application should display this message to the agent.

### Payload
- **botId** (string) - Required - The ID of the bot sending the event.
- **data.eventType** (string) - Required - Set to `widgetMessage`.
- **data.platformConversationId** (string) - Required - The conversation id (external).
- **data.conversationId** (string) - Required - Ultimate internal conversation id (can be ignored).

### Request Example
```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5"
  }
}
```

### Response
- `200 OK` (success, no response body)
- `4XX`–`5XX` (failure)
```

--------------------------------

### AI Agents Ticket API Webhook Event

Source: https://developer.zendesk.com/api-reference/ai-agents/ticket/ticket-webhook

Webhooks allow your application to receive real-time updates from the AI Agents Ticket API. When a ticket event occurs, the API sends an HTTP POST request to your specified endpoint. Your webhook should acknowledge receipt with a 200 OK response. The actual bot response is sent to your webhook URL in a separate request.

```APIDOC
## Webhook Event Structure

The Ticket API webhook delivers a single event type that sends a message from the bot to the visitor interface. Events are delivered as JSON objects with the following properties:

### JSON Format

| Name | Type | Description |
|---|---|---|
| botId | string | The id of the bot sending the event |
| conversationId | string | Internal conversation id |
| platformConversationId | string | External id of the conversation |
| text | string | The text of the message |
| predictedIntents | array of objects | Array of predicted intent objects. Each object must contain: <br> - value: string (intent id) <br> - name: string (intent name) <br> - confidence: number (confidence score, 0–1) |
| attachments | array of objects | Array of attachment objects. Each object must contain: <br> - path: string (file path) |

### Example Webhook Payload

```json
{
  "botId": "618a30beee4e8e87d2f94015",
  "conversationId": "conversation1",
  "platformConversationId": "session1",
  "text": "Hello, this is a bot text message",
  "predictedIntents": [
    {
      "value": "1234",
      "name": "intent name",
      "confidence": 1
    }
  ],
  "attachments": [
    {
      "path": "path/to/attachment"
    }
  ]
}
```

### Response Handling

A successful message event returns an HTTP `200 OK` status with no response body. A failed message returns a `4XX` or `5XX` status code.
```

--------------------------------

### Widget End Session Event

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Handles events when a customer explicitly ends an escalated conversation via the widget.

```APIDOC
## POST /webhooks/widget-escalation

### Description
This endpoint is triggered when a customer explicitly ends an escalated conversation using the Ultimate Chat Widget. Your application should end the connection with the agent and close the conversation upon receiving this event.

### Method
POST

### Endpoint
/webhooks/widget-escalation

### Request Body
- **botId** (string) - Required - The id of the bot sending the event
- **data** (object) - Required
  - **eventType** (string) - Required - "widgetEndSession"
  - **platformConversationId** (string) - Required - The conversation id (external)
  - **conversationId** (string) - Required - Ultimate internal conversation id (can be ignored)

### Request Example
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetEndSession",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5"
  }
}

### Response
#### Success Response (200 OK)
No response body.
```

--------------------------------

### Process SendMessage Event in TypeScript

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Handles the Converse Webhook event specifically for the SEND_MESSAGE type. Logs the received event and provides a placeholder for custom application logic. Other event types can be handled in the default case.

```typescript
/**
 * Handles the Converse Webhook event.
 * @param converseWebhookDto Event payload from the bot
 */
public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
  switch (converseWebhookDto.data.eventType) {
    case ConverseWebhookEventTypes.SEND_MESSAGE:
      // Process messages from the bot (text, button list, carousel, etc.)
      logger.info(
        `Received ${ConverseWebhookEventTypes.SEND_MESSAGE} event: ${JSON.stringify(converseWebhookDto)}`
      );
      // Add your application's logic here
      break;
    default:
      // Handle other event types as needed
      break;
  }
}
```

--------------------------------

### Escalate event

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

The `escalate` event signifies that the bot is requesting to transfer the conversation to a human agent. Upon receiving this event, your application assumes control of the conversation flow.

```APIDOC
## escalate event
The `escalate` event occurs when the bot requests escalation to a human agent. Once this event is received, the bot stops sending messages to the visitor, and your application becomes responsible for managing the conversation flow—such as checking agent availability or adding the customer to a queue.
The template project processes this event using `ConverseWebhookService`. After the event is received, your application is responsible for handling the next steps, such as checking agent availability, adding the customer to a queue, or implementing any other relevant business logic.
```

--------------------------------

### Handle Converse Webhook Events in TypeScript

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

This method processes incoming Converse Webhook events. It receives a DTO with event details and processes the request based on the eventType field. It's crucial to respond with a 200 OK to acknowledge receipt.

```typescript
/**
 * This method processes the Converse Webhook
 * It receives a DTO of type ConverseWebhookDto with the event details
 * It processes the request differently depending on the eventType field
 * of the payload
 * @param req
 * @param res
 * @param next
 */
public processEvent = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
  const requestBody: ConverseWebhookDto = req.body;
  try {
    this.converseWebhookService.processConverseWebhookEvent(requestBody);
    res.status(200).send();
  } catch (error: any) {
    next(error);
  }
};
```

--------------------------------

### Process Converse Webhook Event - widgetMessage (TypeScript)

Source: https://developer.zendesk.com/api-reference/ai-agents/widget-escalation/widget-escalation-webhook

Processes the Converse Webhook event, specifically handling the 'widgetMessage' event type. This event signifies a message from a customer during an escalated conversation using the Ultimate Chat Widget. The message is logged and intended for asynchronous processing.

```typescript
/**     * This method processes the Converse Webhook event.     * @param converseWebhookDto     */    public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
        switch (converseWebhookDto.data.eventType) {
            case ConverseWebhookEventTypes.WIDGET_MESSAGE:
                /**                 * This event represents a message request from the user to an agent in an escalated conversation for customers that are using Ultimate Chat Widget                 *                 * The payload of this event is represented in the BotWidgetEscalateEvent class.                 *                 * The request will be acknowledged and then processed ASYNCHRONOUSLY.                 */                logger.info(
                    `Received ${ConverseWebhookEventTypes.WIDGET_MESSAGE} event: \n ${JSON.stringify(
                        converseWebhookDto
                    )}`
                );
                break;
            default:
                break;
        }
    }}
```

--------------------------------

### sendMessage Event

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

The 'sendMessage' event signifies a message from the bot to the visitor. It can include text, buttons, or carousel cards. Your webhook should process this event asynchronously.

```APIDOC
## sendMessage Event Details

### Description
Represents a message sent from the bot to the visitor. Can be a simple text message, a list of buttons, or carousel cards.

### Event Type
sendMessage

### Data Fields
- **botId** (string) - The ID of the bot sending the event.
- **eventType** (string) - Set to `sendMessage`.
- **platformConversationId** (string) - External conversation ID.
- **conversationId** (string) - Internal conversation ID (can be ignored).
- **type** (string) - Set to `text` for a text message.
- **replyId** (string) - The reply ID that triggered this message.
- **text** (string) - The text content of the message.
- **buttons** (array) - Always empty for a simple text message.
- **carouselCards** (array) - Always empty for a simple text message.
- **predictedIntents** (array) - Array of predicted intents for visitor message. Each object must contain:
  - **value** (string) - Intent ID.
  - **name** (string) - Intent name.
  - **confidence** (number) - Confidence score (0–1).

### Example Payload
```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "sendMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "type": "text",
    "replyId": "REPLY_ID",
    "buttons": [],
    "text": "Hello, this is a bot text message",
    "carouselCards": [],
    "predictedIntents": [
      { "value": "1234", "name": "intent name", "confidence": 1 }
    ]
  }
}
```
```

--------------------------------

### Carousel message

Source: https://developer.zendesk.com/api-reference/ai-agents/chat/chat-webhook

Represents a message from the bot containing a carousel of cards, each with optional buttons. The `data.type` should be set to `carousel` for this message type.

```APIDOC
## Carousel message
A message from the bot containing a carousel of cards, each with optional buttons.

### Fields
- **botId** (string): The id of the bot sending the event
- **data.eventType** (string): Set to `sendMessage`
- **data.platformConversationId** (string): Conversation id (external)
- **data.conversationId** (string): (Optional) Internal conversation id
- **data.type** (string): Set to `carousel`
- **data.replyId** (string): The reply id that triggered this message
- **data.text** (string): Optional. Message text (can be omitted for carousels)
- **data.buttons** (array): Always empty for a carousel message
- **data.carouselCards** (array): Array of CarouselCard objects. See CarouselCard
- **data.predictedIntents** (array): Array of predicted intent objects. Each object must contain:
    - value: string (intent id)
    - name: string (intent name)
    - confidence: number (confidence score, 0–1)

#### CarouselCard
Each object of type `CarouselCard` in the array must contain the following fields:
- **title** (string): Title of the carousel card
- **description** (string): Description of the card
- **imageUrl** (string): URL to the card image
- **buttons** (array): Each object of type `Button` must contain the following fields:
    - type: string (set to the value "button")
    - text:string (button text)

### Example
```json
{
  "botId": "BOT_ID",
  "data": {
    "eventType": "sendMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "type": "carousel",
    "replyId": "REPLY_ID",
    "buttons": [],
    "text": "",
    "carouselCards": [
      {
        "title": "card 1",
        "description": "card 1 description",
        "imageUrl": "URL",
        "buttons": [
          { "text": "button 1", "type": "button" },
          { "text": "button 2", "type": "button" }
        ]
      },
      {
        "title": "card 2",
        "description": "card 2 description",
        "imageUrl": "URL",
        "buttons": [
          { "text": "button 1", "type": "button" },
          { "text": "button 2", "type": "button" }
        ]
      }
    ],
    "predictedIntents": [
      { "value": "1234", "name": "intent name", "confidence": 1 }
    ]
  }
}
```
```

--------------------------------

### Delete User Data Request Body

Source: https://developer.zendesk.com/api-reference/ai-agents/delete-user-data/delete-user-data

Use this JSON body to specify the conversation IDs for which user data should be deleted. Ensure conversation IDs are provided as strings.

```json
{
  "conversationIds": ["123456789", "987654321"]
}
```