### Get Token Info Request Example

Source: https://developer.zendesk.com/api-reference/conversations

This example demonstrates how to make a GET request to the tokenInfo endpoint to retrieve information about the app linked to the OAuth token. This is useful for obtaining the app's ID and subdomain for subsequent API calls.

```http
GET https://oauth-bridge.zendesk.com/sc/v2/tokenInfo

```

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

### List Participants Request Example

Source: https://developer.zendesk.com/api-reference/conversations

Example of a GET request to list participants in a conversation, including cursor pagination parameters.

```bash
/v2/apps/:appId/conversations/:conversationId/participants?page[before]=26508c10541a4b0ff472e5e2

```

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

### List Apps Request URL Example

Source: https://developer.zendesk.com/api-reference/conversations

Example URL for listing apps with cursor pagination parameters. Use 'page[after]' for the cursor and 'page[size]' to control the number of results per page.

```bash
/v2/apps?page[after]=5e1606762556d93e9c176f69&page[size]=10
```

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

### List Integrations API Endpoint Example

Source: https://developer.zendesk.com/api-reference/conversations

Example of how to call the List Integrations API endpoint with pagination and filtering parameters. This helps retrieve a paginated list of available integrations.

```bash
/v2/apps/:appId/integrations?page[after]=5e1606762556d93e9c176f69&page[size]=10&filter[types]=custom,web

```

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

### Get App

Source: https://developer.zendesk.com/api-reference/conversations

Fetches an individual app.

```APIDOC
## Get App 
GET /v2/apps/{appId}

### Description
Fetches an individual app.

### Method
GET

### Endpoint
/v2/apps/{appId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.

### Response
#### Success Response (200)
- **app** (object) - The app.

#### Response Example
```json
{
  "app": {
    "id": "67a0e55ef0305f4a391e9d69",
    "displayName": "My Test App",
    "settings": {
      "appLocalizationEnabled": true,
      "echoPostback": false,
      "maskCreditCardNumbers": true,
      "multiConvoEnabled": false,
      "useAnimalNames": false
    }
  }
}
```
```

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

### Create App Response Sample (201 Created)

Source: https://developer.zendesk.com/api-reference/conversations

Example of a successful response when creating an app. It returns the created app's details, including its ID and settings.

```json
{
  "app": {
    "id": "67a0e55ef0305f4a391e9d69",
    "displayName": "My Test App",
    "settings": {
      "appLocalizationEnabled": true,
      "echoPostback": false,
      "maskCreditCardNumbers": true,
      "multiConvoEnabled": false,
      "useAnimalNames": false
    }
  }
}
```

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

### API Path for Listing Clients

Source: https://developer.zendesk.com/api-reference/conversations

This is an example of a paginated API path for retrieving a list of clients associated with a user.

```bash
/v2/apps/:appId/users/:userId/clients?page[after]=5ebee0975ac5304b664a12fa
```

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

### List Users API Endpoint Example

Source: https://developer.zendesk.com/api-reference/conversations

This is an example of how to construct a URL to list users filtered by their email identity. The `filter[identities.email]` parameter is required for this endpoint.

```bash
/v2/apps/:appId/users?filter[identities.email]=sue@example.org
```

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

### Initiate OAuth Flow

Source: https://developer.zendesk.com/api-reference/conversations

Starts the OAuth flow by redirecting the user to the authorization endpoint. Ensure the base URL is correctly set to `oauth-bridge.zendesk.com/sc`.

```http
https://oauth-bridge.zendesk.com/sc/oauth/authorize?response_type=code&client_id={client_id}
```

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

### Get Switchboards

Source: https://developer.zendesk.com/api-reference/conversations

Retrieves a list of switchboards for a given app.

```APIDOC
## Get Switchboards

### Description
Retrieves a list of switchboards for a given app.

### Method
GET

### Endpoint
/v2/apps/{appId}/switchboards

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.

### Responses
#### Success Response (200)
- **switchboards** (Array of objects) - List of returned switchboards.

#### Response Example
```json
{
  "switchboards": [
    {
      "id": "5ef21b132f21af34f088530d",
      "enabled": false
    }
  ]
}
```
```

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

### Response Sample for Posting a Message

Source: https://developer.zendesk.com/api-reference/conversations

This is an example of a successful response when posting a message to a conversation. It includes message details like ID, timestamp, author, and content.

```json
{
  "messages": [
    {
      "id": "5f748c1a2b5315fc007e7977",
      "received": "2020-09-30T13:46:02.733Z",
      "author": {
        "type": "business",
        "avatarUrl": "https://www.gravatar.com/image.jpg"
      },
      "content": {
        "type": "text",
        "text": "Hello!"
      },
      "source": {
        "type": "api:conversations"
      }
    }
  ]
}
```

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

### Get Integration

Source: https://developer.zendesk.com/api-reference/conversations

Retrieves details of a specific integration associated with an app.

```APIDOC
## Get Integration 
get/v2/apps/{appId}/integrations/{integrationId}

### Description
Get integration.

### Method
GET

### Endpoint
https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/integrations/{integrationId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **integrationId** (string) - Required - The id of the integration.

### Responses
#### Success Response (200)
- **integration** (object) - The integration.

#### Response Example
```json
{
  "integration": {
    "id": "5e4af71a81966cfff3ef6550",
    "type": "android",
    "status": "active",
    "displayName": "Android SDK"
  }
}
```
```

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

### Get User

Source: https://developer.zendesk.com/api-reference/conversations

Fetches an individual user by their ID or external ID.

```APIDOC
## GET /v2/apps/{appId}/users/{userIdOrExternalId}

### Description
Fetches an individual user's details.

### Method
GET

### Endpoint
/v2/apps/{appId}/users/{userIdOrExternalId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **userIdOrExternalId** (string) - Required - The user's id or externalId.

### Response
#### Success Response (200)
- **user** (object) - The user object.

#### Response Example
```json
{
  "user": {
    "id": "67a11490f0305f4a391e9f8a",
    "externalId": "your-own-id",
    "zendeskId": "35436",
    "signedUpAt": "2025-02-03T19:10:08.152Z",
    "hasPaymentInfo": false,
    "identities": [],
    "profile": {
      "locale": "en",
      "localeOrigin": "zendeskAccount"
    },
    "metadata": {}
  }
}
```
```

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

### Get Switchboard Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample JSON response for retrieving switchboard information. It includes the switchboard ID and its enabled status.

```json
{
  "switchboards": [
    {
      "id": "5ef21b132f21af34f088530d",
      "enabled": false
}
]

}
```

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

### Get Integration Key

Source: https://developer.zendesk.com/api-reference/conversations

Retrieves the specified API key for an integration. Supports multiple server endpoints.

```APIDOC
## Get Integration Key 
get/v2/apps/{appId}/integrations/{integrationId}/keys/{keyId}

### Description
Get the specified API key.

### Method
GET

### Endpoint
- https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/integrations/{integrationId}/keys/{keyId}
- https://api.smooch.io/v2/apps/{appId}/integrations/{integrationId}/keys/{keyId} (US server)
- https://api.eu-1.smooch.io/v2/apps/{appId}/integrations/{integrationId}/keys/{keyId} (EU server)

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **integrationId** (string) - Required - The id of the integration.
- **keyId** (string) - Required - The id of the key.

### Responses
#### Success Response (200)
- **key** (object (apiKey)) - The integration key.

### Response Example (200)
```json
{
  "key": {
    "id": "int_67a1110ef0305f4a391e9f01",
    "displayName": "My Test Key",
    "secret": "JWSooRf7mjKYQereu5ueIjxKdclNs7cdCDaT7bGHEitHFUbNxFb8C0Cwi0s7SG0vhjMDef_w5d-TVetWHanIBA"
  }
}
```
```

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

### Get Token Info Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

This JSON object represents a successful response from the tokenInfo endpoint. It provides details about the associated app, including its ID, display name, settings, metadata, and subdomain.

```json
{
  "app": {
    "id": "5d8cff3cd55b040010928b5b",
    "displayName": "My App",
    "settings": {
      "conversationRetentionSeconds": 0,
      "maskCreditCardNumbers": true,
      "useAnimalNames": true,
      "echoPostback": true,
      "ignoreAutoConversationStart": true,
      "multiConvoEnabled": true,
      "appLocalizationEnabled": true,
      "endSessionEnabled": true,
      "disableConversationReopen": true
},
    "metadata": {
      "lang": "en-ca"
},
    "subdomain": "test-domain"
}

}
```

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

### Update Integration Request Sample

Source: https://developer.zendesk.com/api-reference/conversations

Example JSON payload for updating an integration. You can modify fields like `displayName`. Ensure the request body adheres to the specified schema for the integration type.

```json
{
  "displayName": "My Test Integration"

}
```

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

### Get Device Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

This JSON object represents a successful response when fetching a specific device. It contains detailed information about the device, including its ID, client ID, integration ID, type, status, and last seen timestamp.

```json
{
  "device": {
    "id": "5d9b870dda96abc332625ccc",
    "guid": "f1c7abea2d49429db10094be820d5f80",
    "clientId": "5d9b870dda96abc332625cc8",
    "integrationId": "5d83a25d9916b64a83ed25e8",
    "type": "web",
    "status": "active",
    "info": {
      "currentTitle": "My Web Page",
      "currentUrl": "https://example.com",
      "browserLanguage": "en-US",
      "referrer": "https://example.com",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36",
      "URL": "example.com",
      "sdkVersion": "0.1",
      "vendor": "zendesk"
},
    "lastSeen": "2025-01-28T17:59:58.331Z"
}

}
```

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

### Get Device

Source: https://developer.zendesk.com/api-reference/conversations

Fetches a specific Device associated with a user and app. This endpoint requires authentication and provides details about a user's device within the Zendesk ecosystem.

```APIDOC
## Get Device 
get/v2/apps/{appId}/users/{userIdOrExternalId}/devices/{deviceId}

### Description
Fetches a specific Device.

### Method
GET

### Endpoint
`https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/users/{userIdOrExternalId}/devices/{deviceId}`

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **userIdOrExternalId** (string) - Required - The user's id or externalId.
- **deviceId** (string) - Required - The device's id.

### Responses
#### Success Response (200)
- **device** (object) - The device.
  - **id** (string)
  - **guid** (string)
  - **clientId** (string)
  - **integrationId** (string)
  - **type** (string)
  - **status** (string)
  - **info** (object)
    - **currentTitle** (string)
    - **currentUrl** (string)
    - **browserLanguage** (string)
    - **referrer** (string)
    - **userAgent** (string)
    - **URL** (string)
    - **sdkVersion** (string)
    - **vendor** (string)
  - **lastSeen** (string)

#### Error Response (404)
Not found
```

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

### JWT Header Example

Source: https://developer.zendesk.com/api-reference/conversations

The JWT header must include the key ID (kid) and specify the algorithm (alg) as HS256. Unsigned JWTs are not accepted.

```json
{
    "alg": "HS256",
    "typ": "JWT",
    "kid": "act_5963ceb97cde542d000dbdb1"
}
```

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

### App Creation Response (200 OK)

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample successful response when creating or retrieving an app. It includes the app's ID, display name, and configured settings.

```json
{
  "app": {
    "id": "67a0e55ef0305f4a391e9d69",
    "displayName": "My Test App",
    "settings": {
      "appLocalizationEnabled": true,
      "echoPostback": false,
      "maskCreditCardNumbers": true,
      "multiConvoEnabled": false,
      "useAnimalNames": false
}
}

}
```

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

### Get Webhook

Source: https://developer.zendesk.com/api-reference/conversations

Gets the specified webhook associated with a Sunshine Conversations Connect integration or a custom integration.

```APIDOC
## GET /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}

### Description
Gets the specified webhook associated with a Sunshine Conversations Connect integration or a custom integration.

### Method
GET

### Endpoint
https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **integrationId** (string) - Required - The id of the integration.
- **webhookId** (string) - Required - The id of the webhook.

### Responses
#### Success Response (200)
- **webhook** (object) - The webhook.

#### Error Response (404)
Not found
```

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

### Response Sample for Listing Clients

Source: https://developer.zendesk.com/api-reference/conversations

This JSON response contains a list of clients for a user, including metadata for pagination.

```json
{
  "clients": [
    {
      "id": "67a0ee38f0305f4a391e9def",
      "type": "sdk",
      "status": "active",
      "lastSeen": "2025-02-03T16:26:32.575Z",
      "linkedAt": "2025-02-03T16:26:32.575Z"
}
],
  "meta": {
    "hasMore": false
}

}
```

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

### Get Conversation

Source: https://developer.zendesk.com/api-reference/conversations

Fetches an individual conversation by its ID.

```APIDOC
## Get Conversation 
GET /v2/apps/{appId}/conversations/{conversationId}

### Description
Fetches an individual conversation.

### Method
GET

### Endpoint
/v2/apps/{appId}/conversations/{conversationId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **conversationId** (string) - Required - Identifies the conversation.

### Responses
#### Success Response (200)
- **conversation** (object) - The conversation.

#### Error Response (404)
Not found
```

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

### Create Client

Source: https://developer.zendesk.com/api-reference/conversations

Creates a client and links it to a channel. The client is initially created with a 'pending' status.

```APIDOC
## Create Client

### Description
Create a client and link it to a channel specified by the `matchCriteria.type`. Note that the client is initially created with a `pending` status. The status of the linking request can be tracked by listening to the `client:add`, `client:update` and `client:removed` webhooks. For more information, see channel transfer.

### Method
POST

### Endpoint
/v2/apps/{appId}/users/{userIdOrExternalId}/clients

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **userIdOrExternalId** (string) - Required - The user's id or externalId.

#### Request Body
- **matchCriteria** (any) - Required - The set of criteria used to determine the user's identity on a third-party channel.
- **confirmation** (object) - Required - The confirmation options of the link request.
- **target** (object) - Required - The target conversation to attach the client to.

### Responses
#### Success Response (201)
- **client** (object) - The client.

```

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

### User Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

A sample JSON response for a user object.

```json
{
  "user": {
    "id": "67a11490f0305f4a391e9f8a",
    "externalId": "your-own-id",
    "signedUpAt": "2025-02-03T19:10:08.152Z",
    "hasPaymentInfo": false,
    "identities": [ ],
    "profile": { },
    "metadata": { }
}

}
```

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

### List Apps Response Sample (200 Ok)

Source: https://developer.zendesk.com/api-reference/conversations

A successful response when listing apps. It returns an array of app objects, including their IDs, display names, and settings, along with metadata and pagination links.

```json
{
  "apps": [
    {
      "id": "67a0e55ef0305f4a391e9d69",
      "displayName": "My Test App",
      "settings": {
        "appLocalizationEnabled": true,
        "echoPostback": false,
        "maskCreditCardNumbers": true,
        "multiConvoEnabled": false,
        "useAnimalNames": false
      }
    }
  ]
}
```

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

### Get Token

Source: https://developer.zendesk.com/api-reference/conversations

Exchanges an authorization code for an access token. This endpoint should only be used in server-to-server calls.

```APIDOC
## Get Token

### Description
This endpoint is used to exchange an authorization code for an access token. It should only be used in server-to-server calls.

Use `oauth-bridge.zendesk.com/sc` as the base URL when invoking this endpoint.

### Method
POST

### Endpoint
/oauth/token

### Request Body schema: application/json
- **code** (string) - Required - The authorization code received via the OAuth flow
- **grant_type** (string) - Required - Must be set to the string `authorization_code`
- **client_id** (string) - Required - Your OAuth client ID, provisioned during the partner application process
- **client_secret** (string) - Required - Your OAuth client secret, provisioned during the partner application process

### Request Example
```json
{
  "code": "658965",
  "grant_type": "authorization_code",
  "client_id": "5e4af71a81966cfff3ef6550",
  "client_secret": "5XJ85yjUtRcaQu_pDINblPZb"
}
```

### Responses
#### Success Response (200)
Ok
##### Response Schema: application/json
- **access_token** (string) - An access token that can now be used to call Sunshine Conversations APIs.
- **token_type** (string) - Bearer. All issued tokens are of this type.

##### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFwcF82N2EyNDBlY2M0OTk3OTAzNTg0YTNjNDgiLCJhenAiOiJzaG9wbGlmdGVyIn0.eyJzY29wZSI6ImludGVncmF0aW9uIiwiYXBwSWQiOiI1Njk4ZWRiZjJhNDNiZDA4MWJlOTgyZjEiLCJpYXQiOjE3Mzg2ODY3MDF9.vm9Bn84ALC9phe-6oo9-qZtm7LiGzZPVmmQd1mpeY7Y",
  "token_type": "Bearer"
}
```
```

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

### Synchronize User Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

A sample JSON response after successfully synchronizing a user, including updated user details.

```json
{
  "user": {
    "id": "67a11490f0305f4a391e9f8a",
    "externalId": "your-own-id",
    "zendeskId": "35436",
    "signedUpAt": "2025-02-03T19:10:08.152Z",
    "hasPaymentInfo": false,
    "identities": [ ],
    "profile": {
      "locale": "en",
      "localeOrigin": "zendeskAccount"
},
    "metadata": { }
}

}
```

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

### Create App Key Response (201 Created)

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample successful response when creating an app key. It includes the key's ID, display name, and secret.

```json
{
  "key": {
    "id": "app_67a0e949f0305f4a391e9d97",
    "displayName": "My Test Key",
    "secret": "2vErhBhv81FZ5YXbC5XElVcnoNSqz0XjhqSYII4AOT3GCA5UojDCT07Z9NG_4PVzcxv-Zdd7IpeBL-RcXvfOyw"
}

}
```

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

### Get App Key

Source: https://developer.zendesk.com/api-reference/conversations

Retrieves a specific API key for an app. Supports Basic and Bearer authentication.

```APIDOC
## GET /v2/apps/{appId}/keys/{keyId}

### Description
Returns an API key.

### Method
GET

### Endpoint
/v2/apps/{appId}/keys/{keyId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **keyId** (string) - Required - The id of the key.

### Responses
#### Success Response (200)
- **key** (object) - The created key object.
  - **id** (string)
  - **displayName** (string)
  - **secret** (string)

#### Error Response (404)
Not found
```

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

### List Webhooks Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample JSON response when listing all webhooks for an integration. It returns an array of webhook objects.

```json
{
  "webhooks": [
    {
      "id": "5e554d2cac66fb73a3c01871",
      "version": "v2",
      "target": "https://example.com/callback",
      "triggers": [
        "conversation:read",
        "conversation:message"
],
      "secret": "8564b3e6a8b20a4bdb68b05ce9bc5936",
      "includeFullUser": false,
      "includeFullSource": false
}
]

}
```

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

### List App Keys Response (200 OK)

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample successful response when listing app keys. It returns an array of key objects, each containing an ID, display name, and secret.

```json
{
  "keys": [
    {
      "id": "app_67a0e949f0305f4a391e9d97",
      "displayName": "My Test Key",
      "secret": "2vErhBhv81FZ5YXbC5XElVcnoNSqz0XjhqSYII4AOT3GCA5UojDCT07Z9NG_4PVzcxv-Zdd7IpeBL-RcXvfOyw"
}
]

}
```

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

### Create Integration Response (201 Created)

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample successful response when an integration is created. It includes the integration's ID, type, status, and display name.

```json
{
  "integration": {
    "id": "5e4af71a81966cfff3ef6550",
    "type": "android",
    "status": "active",
    "displayName": "Android SDK"
}

}
```

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

### List Conversations Request URL

Source: https://developer.zendesk.com/api-reference/conversations

Example URL for listing conversations, filtered by a specific user ID. This API uses cursor pagination.

```bash
/v2/apps/:appId/conversations?filter[userId]=42589ad070d43be9b00ff7e5
```

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

### Synchronize User Request Sample

Source: https://developer.zendesk.com/api-reference/conversations

A sample JSON payload for synchronizing a user, specifying the surviving Zendesk user ID in case of a merge.

```json
{
  "survivingZendeskId": "35436"

}
```

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

### List Integrations Response (200 Ok)

Source: https://developer.zendesk.com/api-reference/conversations

Sample successful response for the List Integrations API. It returns an array of integration objects, metadata about pagination, and links for next/previous pages.

```json
{
  "integrations": [
    {
      "id": "5e4af71a81966cfff3ef6550",
      "type": "android",
      "status": "active",
      "displayName": "Android SDK"
}
],
  "meta": {
    "hasMore": false
}

}
```

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

### List App Keys

Source: https://developer.zendesk.com/api-reference/conversations

Lists all API keys for a given app.

```APIDOC
## List App Keys

GET /v2/apps/{appId}/keys

### Description
Lists all API keys for a given app.

### Method
GET

### Endpoint
https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/keys

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.

### Responses
#### Success Response (200)
Ok
##### Response Schema: application/json
```json
{
  "keys": [
    {
      "id": "string",
      "displayName": "string",
      "secret": "string"
    }
  ]
}
```

#### Response Example (200)
```json
{
  "keys": [
    {
      "id": "app_67a0e949f0305f4a391e9d97",
      "displayName": "My Test Key",
      "secret": "2vErhBhv81FZ5YXbC5XElVcnoNSqz0XjhqSYII4AOT3GCA5UojDCT07Z9NG_4PVzcxv-Zdd7IpeBL-RcXvfOyw"
    }
  ]
}
```
```

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

### List Devices Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

This JSON object represents a successful response when listing devices associated with a user. It includes details for each device, such as its ID, type, status, and last seen information.

```json
{
  "devices": [
    {
      "id": "5d9b870dda96abc332625ccc",
      "guid": "f1c7abea2d49429db10094be820d5f80",
      "clientId": "5d9b870dda96abc332625cc8",
      "integrationId": "5d83a25d9916b64a83ed25e8",
      "type": "web",
      "status": "active",
      "info": {
        "currentTitle": "My Web Page",
        "currentUrl": "https://example.com",
        "browserLanguage": "en-US",
        "referrer": "https://example.com",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36",
        "URL": "example.com",
        "sdkVersion": "0.1",
        "vendor": "zendesk"
},
      "lastSeen": "2025-01-28T17:59:58.331Z"
}
]

}
```

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

### Create User

Source: https://developer.zendesk.com/api-reference/conversations

Creates a new user within the specified application.

```APIDOC
## Create User

### Description
Creates a new user.

### Method
POST

### Endpoint
`/v2/apps/{appId}/users`

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.

### Responses
**200**
Ok
##### Response Schema: application/json
object
**404**
Not found
```

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

### App-Scoped JWT Payload Example

Source: https://developer.zendesk.com/api-reference/conversations

For app-scoped JWTs, the payload must include a 'scope' claim set to 'app'. These JWTs are generated using API keys associated with an app.

```json
{
   "scope": "app"
}
```

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

### Get Token Info

Source: https://developer.zendesk.com/api-reference/conversations

Retrieves the app linked to the OAuth token. This is useful for obtaining the app's ID and subdomain after receiving an access token, and can also confirm credential validity.

```APIDOC
## Get Token Info 
GET /v2/tokenInfo

### Description
This endpoint can be used to retrieve the app linked to the OAuth token. Typically used after receiving an access token via OAuth, in order to retrieve the app's `id` and `subdomain` to be used in future calls. May also be used to confirm that the credentials are still valid.

### Method
GET

### Endpoint
`https://oauth-bridge.zendesk.com/sc/v2/tokenInfo`

### Responses
#### Success Response (200)
- **app** (object) - The app.
  - **id** (string)
  - **displayName** (string)
  - **settings** (object)
    - **conversationRetentionSeconds** (number)
    - **maskCreditCardNumbers** (boolean)
    - **useAnimalNames** (boolean)
    - **echoPostback** (boolean)
    - **ignoreAutoConversationStart** (boolean)
    - **multiConvoEnabled** (boolean)
    - **appLocalizationEnabled** (boolean)
    - **endSessionEnabled** (boolean)
    - **disableConversationReopen** (boolean)
  - **metadata** (object)
    - **lang** (string)
  - **subdomain** (string)
```

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

### Request Sample for Posting Activity

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample JSON payload for the 'Post Activity' endpoint. It includes author details and the activity type, such as a read event.

```json
{
  "author": {
    "type": "user",
    "userId": "5963c0d619a30a2e00de36b8"
},
  "type": "conversation:read"

}
```

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

### Create Conversation Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample response when a conversation is successfully created.

```json
{
  "conversation": {
    "id": "67a0ecf8f0305f4a391e9db1",
    "type": "personal",
    "isDefault": false,
    "lastUpdatedAt": "2025-02-03T16:21:12.308Z",
    "createdAt": "2025-02-03T16:21:12.308Z"
}

}
```

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

### Error Response Example

Source: https://developer.zendesk.com/api-reference/conversations

This JSON object illustrates a typical error response structure, including an array of errors with codes and titles. This format is generally returned for 4xx status codes.

```json
{
   "errors":  [
    {
        "code": "unauthorized",
        "title": "Authorization is required"
    }
   ]
}
```

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

### Create User

Source: https://developer.zendesk.com/api-reference/conversations

Creates a new user in Zendesk. This endpoint allows for detailed user information, including profile and metadata.

```APIDOC
## POST /users

### Description
Creates a new user with provided details.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **externalId** (string) - Required - A unique identifier for the user.
- **signedUpAt** (string) - Optional - The date at which the user signed up. Must be ISO 8601 time format.
- **toBeRetained** (boolean) - Optional - Flag indicating whether a user should be retained after inactivity.
- **profile** (object) - Optional - Object hosting user profile information.
- **metadata** (object) - Optional - Flat object containing custom properties (strings, numbers, booleans).

### Request Example
```json
{
  "externalId": "your-own-id",
  "signedUpAt": "2020-05-21T15:53:30.197Z",
  "toBeRetained": true,
  "profile": {
    "givenName": "Jane",
    "surname": "Doe",
    "email": "jane.doe@gmail.com",
    "avatarUrl": "https://s3.amazonaws.com/avatar.jpg",
    "locale": "fr-CA"
  },
  "metadata": {
    "lang": "en-ca"
  }
}
```

### Response
#### Success Response (201)
- **user** (object) - The created user.

#### Response Example
```json
{
  "user": {
    "id": "67a11490f0305f4a391e9f8a",
    "externalId": "your-own-id",
    "signedUpAt": "2025-02-03T19:10:08.152Z",
    "hasPaymentInfo": false,
    "identities": [],
    "profile": {
      "locale": "en",
      "localeOrigin": "zendeskAccount"
    },
    "metadata": {}
  }
}
```
```

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

### Get User Response Body (200 OK)

Source: https://developer.zendesk.com/api-reference/conversations

This JSON object shows a successful response when fetching an individual user. It includes the user's ID, external ID, and associated profile and metadata.

```json
{
  "user": {
    "id": "67a11490f0305f4a391e9f8a",
    "externalId": "your-own-id",
    "zendeskId": "35436",
    "signedUpAt": "2025-02-03T19:10:08.152Z",
    "hasPaymentInfo": false,
    "identities": [ ],
    "profile": {
      "locale": "en",
      "localeOrigin": "zendeskAccount"
    },
    "metadata": { }
  }
}
```

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

### Example Conversation Event Payload

Source: https://developer.zendesk.com/api-reference/conversations

This JSON payload represents a client:add event within the Zendesk Conversations API. It details the app, webhook, and event specifics, including conversation and user information.

```json
{
  "app": {
    "id": "60bf823452c2a718162f986a"
},
  "webhook": {
    "id": "612905a67821c3f206d6909f",
    "version": "v2"
},
  "events": [
    {
      "id": "61290a62c64b3af1ff868714",
      "createdAt": "2021-08-27T15:53:06.744Z",
      "type": "client:add",
      "payload": {
        "conversation": {
          "id": "c2c8710dedf8f26ee6e9a68f",
          "type": "personal"
},
        "user": {
          "id": "6a2343df57be6fe0f98efc33",
          "authenticated": false
},
        "client": {
          "integrationId": "60bfc8fa67951336472cc57a",
          "type": "twilio",
          "id": "61290a4f7821c3f206d690a3",
          "status": "pending"
},
        "reason": "channelLinking",
        "source": {
          "type": "web",
          "integrationId": "60bf824952c2a718162f989c"
}
}
}
]

}
```

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

### List Integration Keys

Source: https://developer.zendesk.com/api-reference/conversations

Lists all API keys for a given integration. Supports multiple server endpoints.

```APIDOC
## List Integration Keys 
get/v2/apps/{appId}/integrations/{integrationId}/keys

### Description
Lists all API keys for a given integration.

### Method
GET

### Endpoint
- https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/integrations/{integrationId}/keys
- https://api.smooch.io/v2/apps/{appId}/integrations/{integrationId}/keys (US server)
- https://api.eu-1.smooch.io/v2/apps/{appId}/integrations/{integrationId}/keys (EU server)

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **integrationId** (string) - Required - The id of the integration.

### Responses
#### Success Response (200)
- **keys** (Array of objects (apiKey)) - Integration keys of the supplied integration.

### Response Example (200)
```json
{
  "keys": [
    {
      "id": "int_67a1110ef0305f4a391e9f01",
      "displayName": "My Test Key",
      "secret": "JWSooRf7mjKYQereu5ueIjxKdclNs7cdCDaT7bGHEitHFUbNxFb8C0Cwi0s7SG0vhjMDef_w5d-TVetWHanIBA"
    }
  ]
}
```
```

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

### Account-Scoped JWT Payload Example

Source: https://developer.zendesk.com/api-reference/conversations

For account-scoped JWTs, the payload must include a 'scope' claim set to 'account'. These JWTs are generated using API keys associated with a Sunshine Conversations account or service account.

```json
{
    "scope": "account"
}
```

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

### Webhook Response Sample

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample JSON response when creating or retrieving a single webhook.

```json
{
  "webhook": {
    "id": "5e554d2cac66fb73a3c01871",
    "version": "v2",
    "target": "https://example.com/callback",
    "triggers": [
      "conversation:read",
      "conversation:message"
],
    "secret": "8564b3e6a8b20a4bdb68b05ce9bc5936",
    "includeFullUser": false,
    "includeFullSource": false
}

}
```

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

### Create Switchboard Integration

Source: https://developer.zendesk.com/api-reference/conversations

Creates a switchboard integration for a given switchboard.

```APIDOC
## Create Switchboard Integration

### Description
Creates a switchboard integration for a given switchboard.

### Method
POST

### Endpoint
/v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.
- **switchboardId** (string) - Required - Identifies the switchboard.
```

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

### Default API Host

Source: https://developer.zendesk.com/api-reference/conversations

Use this API host for all API requests for licensed Zendesk customers. Ensure to always use HTTPS.

```bash
https://{subdomain}.zendesk.com/sc
```

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

### Response Sample for Creating a Conversation

Source: https://developer.zendesk.com/api-reference/conversations

This JSON response indicates the status of a newly created or updated conversation client.

```json
{
  "client": {
    "id": "67a11639f0305f4a391ea02d",
    "integrationId": "5e8b49d936c1df272e8e1460",
    "type": "whatsapp",
    "status": "pending"
}

}
```

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

### Create Switchboard

Source: https://developer.zendesk.com/api-reference/conversations

Creates a new switchboard for the specified app. Supports multiple server endpoints.

```APIDOC
## Create Switchboard 
post/v2/apps/{appId}/switchboards

### Description
Create a switchboard.

### Method
POST

### Endpoint
- https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/switchboards
- https://api.smooch.io/v2/apps/{appId}/switchboards (US server)
- https://api.eu-1.smooch.io/v2/apps/{appId}/switchboards (EU server)

### Parameters
#### Path Parameters
- **appId** (string) - Required - Identifies the app.

### Responses
#### Success Response (201)
- **switchboard** (object) - The created switchboard.

### Response Example (201)
```json
{
  "switchboard": {
    "id": "5ef21b132f21af34f088530d",
    "enabled": false
  }
}
```
```

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

### Create Switchboard Integration Response Body (201 Created)

Source: https://developer.zendesk.com/api-reference/conversations

This is a sample response when a switchboard integration is successfully created. It includes the details of the created integration.

```json
{
  "switchboardIntegration": {
    "id": "5ef21b86e933b7355c11c604",
    "name": "zd-agentWorkspace",
    "integrationId": "5ef21b86e933b7355c11c605",
    "integrationType": "zd:agentWorkspace",
    "deliverStandbyEvents": false
  }
}
```

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

### Create App

Source: https://developer.zendesk.com/api-reference/conversations

Creates a new app. When using service account credentials, the service account is automatically granted access to the app.

```APIDOC
## Create App 
POST /v2/apps

### Description
Creates a new app. When using service account credentials, the service account is automatically granted access to the app.

### Method
POST

### Endpoint
/v2/apps

### Parameters
#### Request Body
- **displayName** (string) - Required - The friendly name of the app. (1 to 100 characters)
- **settings** (object) - Customizable app settings.
- **metadata** (object | null) - Flat object containing custom properties. Strings, numbers and booleans are the only supported format. Limited to 4KB.

### Request Example
```json
{
  "displayName": "My App",
  "settings": {
    "conversationRetentionSeconds": 0,
    "maskCreditCardNumbers": true,
    "useAnimalNames": true,
    "echoPostback": true,
    "ignoreAutoConversationStart": true,
    "multiConvoEnabled": true,
    "appLocalizationEnabled": true,
    "endSessionEnabled": true,
    "disableConversationReopen": true
  },
  "metadata": {
    "lang": "en-ca"
  }
}
```

### Response
#### Success Response (201)
- **app** (object) - The created app.

#### Response Example
```json
{
  "app": {
    "id": "67a0e55ef0305f4a391e9d69",
    "displayName": "My Test App",
    "settings": {
      "appLocalizationEnabled": true,
      "echoPostback": false,
      "maskCreditCardNumbers": true,
      "multiConvoEnabled": false,
      "useAnimalNames": false
    }
  }
}
```
```

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

### Authorize

Source: https://developer.zendesk.com/api-reference/conversations

Begins the OAuth flow. It relies on a browser session for authentication. If the user is not logged in to Zendesk they will be redirected to the login page. If the user has many Zendesk accounts, they will first be prompted to select the one they wish to integrate with. They will then be presented with an Allow/Deny dialog, describing details of the access your integration is requesting.

```APIDOC
## Authorize

### Description
This endpoint begins the OAuth flow. It relies on a browser session for authentication. If the user is not logged in to Zendesk they will be redirected to the login page. If the user has many Zendesk accounts, they will first be prompted to select the one they wish to integrate with. They will then be presented with an Allow/Deny dialog, describing details of the access your integration is requesting.

Use `oauth-bridge.zendesk.com/sc` as the base URL when redirecting the user to this endpoint.

### Method
GET

### Endpoint
/oauth/authorize

### Query Parameters
- **client_id** (string) - Required - Your integration’s unique identifier
- **response_type** (string) - Required - For now the only acceptable value is code.
- **state** (string) - Optional - You may pass in any arbitrary string value here which will be returned to you along with the code via browser redirect.
- **redirect_uri** (string) - Optional - You may pass in a redirect_uri to determine which URI the response is redirected to. This URI must be contained in the list configured by your integration. If this option is not passed, the first URI present in the list will be used.

### Responses
#### Success Response (302)
Found
```

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

### Update User in Zendesk

Source: https://developer.zendesk.com/api-reference/conversations

Updates an existing user's profile and metadata. Ensure the 'signedUpAt' field is in ISO 8601 format.

```json
{
  "signedUpAt": "2020-05-21T15:53:30.197Z",
  "toBeRetained": true,
  "profile": {
    "givenName": "Jane",
    "surname": "Doe",
    "email": "jane.doe@gmail.com",
    "avatarUrl": "https://s3.amazonaws.com/avatar.jpg",
    "locale": "fr-CA"
  },
  "metadata": {
    "lang": "en-ca"
  }
}
```