{"files":{"SKILL.md":"---\nname: sunshine-conversations-api\ndescription: \"Sunshine Conversations API skill. Use when working with Sunshine Conversations for apps, tokenInfo, oauth. Covers 68 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Sunshine Conversations API\nAPI version: 17.9.0\n\n## Auth\nBearer bearer | Bearer basic\n\n## Base URL\nhttps://{subdomain}.zendesk.com/sc\n\n## Setup\n1. Set Authorization header with Bearer token\n2. GET /v2/apps -- list apps\n3. POST /v2/apps -- create first app\n\n## Endpoints\n68 endpoints across 3 groups. See references/api-spec.lap for full details.\n\n### Apps\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /v2/apps | Create App |\n| GET | /v2/apps | List Apps |\n| GET | /v2/apps/{appId} | Get App |\n| PATCH | /v2/apps/{appId} | Update App |\n| DELETE | /v2/apps/{appId} | Delete App |\n| POST | /v2/apps/{appId}/keys | Create App Key |\n| GET | /v2/apps/{appId}/keys | List App Keys |\n| GET | /v2/apps/{appId}/keys/{keyId} | Get App Key |\n| DELETE | /v2/apps/{appId}/keys/{keyId} | Delete App Key |\n| POST | /v2/apps/{appId}/attachments | Upload Attachment |\n| POST | /v2/apps/{appId}/attachments/remove | Delete Attachment |\n| POST | /v2/apps/{appId}/conversations | Create Conversation |\n| GET | /v2/apps/{appId}/conversations | List Conversations |\n| GET | /v2/apps/{appId}/conversations/{conversationId} | Get Conversation |\n| PATCH | /v2/apps/{appId}/conversations/{conversationId} | Update Conversation |\n| DELETE | /v2/apps/{appId}/conversations/{conversationId} | Delete Conversation |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/join | Join Conversation |\n| GET | /v2/apps/{appId}/conversations/{conversationId}/participants | List Participants |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/leave | Leave Conversation |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/messages | Post Message |\n| GET | /v2/apps/{appId}/conversations/{conversationId}/messages | List Messages |\n| DELETE | /v2/apps/{appId}/conversations/{conversationId}/messages | Delete All Messages |\n| DELETE | /v2/apps/{appId}/conversations/{conversationId}/messages/{messageId} | Delete Message |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/activity | Post Activity |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/acceptControl | Accept Control |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/offerControl | Offer Control |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/passControl | Pass Control |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/releaseControl | Release Control |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/download | Download Message Ref |\n| POST | /v2/apps/{appId}/conversations/{conversationId}/conversionEvents | Post Conversion Events |\n| POST | /v2/apps/{appId}/integrations | Create Integration |\n| GET | /v2/apps/{appId}/integrations | List Integrations |\n| GET | /v2/apps/{appId}/integrations/{integrationId} | Get Integration |\n| PATCH | /v2/apps/{appId}/integrations/{integrationId} | Update Integration |\n| DELETE | /v2/apps/{appId}/integrations/{integrationId} | Delete Integration |\n| POST | /v2/apps/{appId}/integrations/{integrationId}/keys | Create Integration Key |\n| GET | /v2/apps/{appId}/integrations/{integrationId}/keys | List Integration Keys |\n| GET | /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId} | Get Integration Key |\n| DELETE | /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId} | Delete Integration Key |\n| POST | /v2/apps/{appId}/integrations/{integrationId}/webhooks | Create Webhook |\n| GET | /v2/apps/{appId}/integrations/{integrationId}/webhooks | List Webhooks |\n| GET | /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId} | Get Webhook |\n| PATCH | /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId} | Update Webhook |\n| DELETE | /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId} | Delete Webhook |\n| POST | /v2/apps/{appId}/switchboards | Create Switchboard |\n| GET | /v2/apps/{appId}/switchboards | List Switchboards |\n| PATCH | /v2/apps/{appId}/switchboards/{switchboardId} | Update Switchboard |\n| DELETE | /v2/apps/{appId}/switchboards/{switchboardId} | Delete Switchboard |\n| POST | /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations | Create Switchboard Integration |\n| GET | /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations | List Switchboard Integrations |\n| PATCH | /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId} | Update Switchboard Integration |\n| DELETE | /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId} | Delete Switchboard Integration |\n| POST | /v2/apps/{appId}/users | Create User |\n| GET | /v2/apps/{appId}/users | List Users |\n| GET | /v2/apps/{appId}/users/{userIdOrExternalId} | Get User |\n| PATCH | /v2/apps/{appId}/users/{userIdOrExternalId} | Update User |\n| DELETE | /v2/apps/{appId}/users/{userIdOrExternalId} | Delete User |\n| POST | /v2/apps/{appId}/users/{userIdOrExternalId}/clients | Create Client |\n| GET | /v2/apps/{appId}/users/{userIdOrExternalId}/clients | List Clients |\n| DELETE | /v2/apps/{appId}/users/{userIdOrExternalId}/clients/{clientId} | Remove Client |\n| GET | /v2/apps/{appId}/users/{userIdOrExternalId}/devices | List Devices |\n| GET | /v2/apps/{appId}/users/{userIdOrExternalId}/devices/{deviceId} | Get Device |\n| DELETE | /v2/apps/{appId}/users/{userIdOrExternalId}/personalinformation | Delete User Personal Information |\n| POST | /v2/apps/{appId}/users/{zendeskId}/sync | Synchronize User |\n\n### TokenInfo\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /v2/tokenInfo | Get Token Info |\n\n### Oauth\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /oauth/authorize | Authorize |\n| POST | /oauth/token | Get Token |\n| DELETE | /oauth/authorization | Revoke Access |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"Create a app?\" -> POST /v2/apps\n- \"List all apps?\" -> GET /v2/apps\n- \"Get app details?\" -> GET /v2/apps/{appId}\n- \"Partially update a app?\" -> PATCH /v2/apps/{appId}\n- \"Delete a app?\" -> DELETE /v2/apps/{appId}\n- \"Create a key?\" -> POST /v2/apps/{appId}/keys\n- \"List all keys?\" -> GET /v2/apps/{appId}/keys\n- \"Get key details?\" -> GET /v2/apps/{appId}/keys/{keyId}\n- \"Delete a key?\" -> DELETE /v2/apps/{appId}/keys/{keyId}\n- \"Create a attachment?\" -> POST /v2/apps/{appId}/attachments\n- \"Create a remove?\" -> POST /v2/apps/{appId}/attachments/remove\n- \"Create a conversation?\" -> POST /v2/apps/{appId}/conversations\n- \"List all conversations?\" -> GET /v2/apps/{appId}/conversations\n- \"Get conversation details?\" -> GET /v2/apps/{appId}/conversations/{conversationId}\n- \"Partially update a conversation?\" -> PATCH /v2/apps/{appId}/conversations/{conversationId}\n- \"Delete a conversation?\" -> DELETE /v2/apps/{appId}/conversations/{conversationId}\n- \"Create a join?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/join\n- \"List all participants?\" -> GET /v2/apps/{appId}/conversations/{conversationId}/participants\n- \"Create a leave?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/leave\n- \"Create a message?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/messages\n- \"List all messages?\" -> GET /v2/apps/{appId}/conversations/{conversationId}/messages\n- \"Delete a message?\" -> DELETE /v2/apps/{appId}/conversations/{conversationId}/messages/{messageId}\n- \"Create a activity?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/activity\n- \"Create a acceptControl?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/acceptControl\n- \"Create a offerControl?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/offerControl\n- \"Create a passControl?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/passControl\n- \"Create a releaseControl?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/releaseControl\n- \"Create a download?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/download\n- \"Create a conversionEvent?\" -> POST /v2/apps/{appId}/conversations/{conversationId}/conversionEvents\n- \"Create a integration?\" -> POST /v2/apps/{appId}/integrations\n- \"List all integrations?\" -> GET /v2/apps/{appId}/integrations\n- \"Get integration details?\" -> GET /v2/apps/{appId}/integrations/{integrationId}\n- \"Partially update a integration?\" -> PATCH /v2/apps/{appId}/integrations/{integrationId}\n- \"Delete a integration?\" -> DELETE /v2/apps/{appId}/integrations/{integrationId}\n- \"Create a webhook?\" -> POST /v2/apps/{appId}/integrations/{integrationId}/webhooks\n- \"List all webhooks?\" -> GET /v2/apps/{appId}/integrations/{integrationId}/webhooks\n- \"Get webhook details?\" -> GET /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}\n- \"Partially update a webhook?\" -> PATCH /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}\n- \"Delete a webhook?\" -> DELETE /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}\n- \"Create a switchboard?\" -> POST /v2/apps/{appId}/switchboards\n- \"List all switchboards?\" -> GET /v2/apps/{appId}/switchboards\n- \"Partially update a switchboard?\" -> PATCH /v2/apps/{appId}/switchboards/{switchboardId}\n- \"Delete a switchboard?\" -> DELETE /v2/apps/{appId}/switchboards/{switchboardId}\n- \"Create a switchboardIntegration?\" -> POST /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations\n- \"List all switchboardIntegrations?\" -> GET /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations\n- \"Partially update a switchboardIntegration?\" -> PATCH /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId}\n- \"Delete a switchboardIntegration?\" -> DELETE /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId}\n- \"Create a user?\" -> POST /v2/apps/{appId}/users\n- \"List all users?\" -> GET /v2/apps/{appId}/users\n- \"Get user details?\" -> GET /v2/apps/{appId}/users/{userIdOrExternalId}\n- \"Partially update a user?\" -> PATCH /v2/apps/{appId}/users/{userIdOrExternalId}\n- \"Delete a user?\" -> DELETE /v2/apps/{appId}/users/{userIdOrExternalId}\n- \"Create a client?\" -> POST /v2/apps/{appId}/users/{userIdOrExternalId}/clients\n- \"List all clients?\" -> GET /v2/apps/{appId}/users/{userIdOrExternalId}/clients\n- \"Delete a client?\" -> DELETE /v2/apps/{appId}/users/{userIdOrExternalId}/clients/{clientId}\n- \"List all devices?\" -> GET /v2/apps/{appId}/users/{userIdOrExternalId}/devices\n- \"Get device details?\" -> GET /v2/apps/{appId}/users/{userIdOrExternalId}/devices/{deviceId}\n- \"Create a sync?\" -> POST /v2/apps/{appId}/users/{zendeskId}/sync\n- \"List all tokenInfo?\" -> GET /v2/tokenInfo\n- \"List all authorize?\" -> GET /oauth/authorize\n- \"Create a token?\" -> POST /oauth/token\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n- Error responses include status codes and descriptions in the spec\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Sunshine Conversations API\n@base https://{subdomain}.zendesk.com/sc\n@version 17.9.0\n@auth Bearer bearer | Bearer basic\n@endpoints 68\n@hint download_for_search\n@toc apps(64), tokenInfo(1), oauth(3)\n\n@group apps\n@endpoint POST /v2/apps\n@desc Create App\n@required {displayName: any # The friendly name of the app.}\n@optional {settings: map{conversationRetentionSeconds: int, maskCreditCardNumbers: bool, useAnimalNames: bool, echoPostback: bool, ignoreAutoConversationStart: bool, multiConvoEnabled: bool, appLocalizationEnabled: bool, endSessionEnabled: bool, disableConversationReopen: bool} # Customizable app settings., metadata: map # Flat object containing custom properties. Strings, numbers and booleans  are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size.}\n@returns(201) {app: any} # Created\n@errors {400: Bad request, 402: Payment required}\n\n@endpoint GET /v2/apps\n@desc List Apps\n@optional {page: map # Contains parameters for applying cursor pagination., filter: map # Contains parameters for filtering the results.}\n@returns(200) {apps: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}} # Ok\n@errors {400: Bad request, 403: Forbidden}\n\n@endpoint GET /v2/apps/{appId}\n@desc Get App\n@returns(200) {app: any} # Ok\n@errors {404: Not found}\n\n@endpoint PATCH /v2/apps/{appId}\n@desc Update App\n@optional {displayName: any # The friendly name of the app., settings: map{conversationRetentionSeconds: int, maskCreditCardNumbers: bool, useAnimalNames: bool, echoPostback: bool, ignoreAutoConversationStart: bool, multiConvoEnabled: bool, appLocalizationEnabled: bool, endSessionEnabled: bool, disableConversationReopen: bool} # Customizable app settings., metadata: map # Flat object containing custom properties. Strings, numbers and booleans  are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size.}\n@returns(200) {app: any} # Ok\n@errors {400: Bad request, 404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}\n@desc Delete App\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/keys\n@desc Create App Key\n@required {displayName: any # The name of the API key.}\n@returns(201) {key: any} # Created\n\n@endpoint GET /v2/apps/{appId}/keys\n@desc List App Keys\n@returns(200) {keys: [map]} # Ok\n\n@endpoint GET /v2/apps/{appId}/keys/{keyId}\n@desc Get App Key\n@returns(200) {key: any} # Ok\n@errors {404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}/keys/{keyId}\n@desc Delete App Key\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/attachments\n@desc Upload Attachment\n@returns(201) {attachment: any} # Created\n@errors {400: Bad request}\n\n@endpoint POST /v2/apps/{appId}/attachments/remove\n@desc Delete Attachment\n@required {mediaUrl: str # The media URL used for a file or image message.}\n@returns(200) Ok\n@errors {400: Bad request, 404: Not found}\n\n@endpoint POST /v2/apps/{appId}/conversations\n@desc Create Conversation\n@required {type: str(personal/sdkGroup) # The type of the conversation.}\n@optional {participants: [any] # The users participating in the conversation. For `personal` conversations, this field is required with a length of exactly 1. For `sdkGroup` conversations, must have a length less than or equal to 10. Can be omitted to have a conversation with no participants if the type is `sdkGroup`., displayName: any # A friendly name for the conversation, may be displayed to the business or the user., description: str # A short text describing the conversation., iconUrl: str(uri) # A custom conversation icon url. The image must be in either JPG, PNG, or GIF format, metadata: map # Flat object containing custom properties. Strings, numbers and booleans  are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size.}\n@returns(201) {conversation: any} # Created\n@errors {404: Not found}\n\n@endpoint GET /v2/apps/{appId}/conversations\n@desc List Conversations\n@required {filter: map # Contains parameters for filtering the results.}\n@optional {page: map # Contains parameters for applying cursor pagination.}\n@returns(200) {conversations: [any], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}} # Ok\n@errors {400: Bad request, 404: Not found}\n\n@endpoint GET /v2/apps/{appId}/conversations/{conversationId}\n@desc Get Conversation\n@returns(200) {conversation: any} # Ok\n@errors {404: Not found}\n\n@endpoint PATCH /v2/apps/{appId}/conversations/{conversationId}\n@desc Update Conversation\n@optional {displayName: any # A friendly name for the conversation, may be displayed to the business or the user., description: str # A short text describing the conversation., iconUrl: str(uri) # A custom conversation icon url. The image must be in either JPG, PNG, or GIF format, metadata: map # Flat object containing custom properties. Strings, numbers and booleans  are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size.}\n@returns(200) {conversation: any} # Ok\n@errors {404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}/conversations/{conversationId}\n@desc Delete Conversation\n@returns(200) Ok\n@errors {400: Bad request, 404: Not found}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/join\n@desc Join Conversation\n@returns(201) {participant: map{id: str, userId: str, unreadCount: int, clientAssociations: [map], userExternalId: str?, lastRead: str?}} # Created\n@errors {400: Bad request, 404: Not found}\n@example_request {\"userId\":\"67a11490f0305f4a391e9f8a\",\"subscribeSDKClient\":true}\n\n@endpoint GET /v2/apps/{appId}/conversations/{conversationId}/participants\n@desc List Participants\n@optional {page: map # Contains parameters for applying cursor pagination.}\n@returns(200) {participants: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}} # Ok\n@errors {400: Bad request, 404: Not found}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/leave\n@desc Leave Conversation\n@returns(200) Ok\n@errors {404: Not found}\n@example_request {\"userId\":\"67a11490f0305f4a391e9f8a\"}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/messages\n@desc Post Message\n@required {author: any # The author of the message., content: any # The content of the message.}\n@optional {destination: any # The destination of the message, in the case of [channel targeting](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/sending-messages/#targeting-a-specific-channel) or sending [silent messages](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/sending-messages/#silent-messages). Only applicable if the author role is `business` and the conversation is of type `personal`., metadata: map # Flat object containing custom properties. Strings, numbers and booleans  are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size., override: any # A raw payload containing a message that is sent directly to a channel. See [message overrides](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/message-overrides/) for more information., schema: str # When `schema` is set to `\"whatsapp\"`, the `content` key is expected to conform to the [native WhatsApp schema](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates) for sending message templates. For more details, consult the documentation for [sending message templates on WhatsApp](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/message-overrides/#template-messages).}\n@returns(201) {messages: [map]} # Created\n@errors {423: Message limit reached Note: To learn more about the conversation message limit, consult the section in the introduction linked here.}\n@example_request {\"author\":{\"type\":\"business\"},\"content\":{\"type\":\"text\",\"text\":\"Hello!\"}}\n\n@endpoint GET /v2/apps/{appId}/conversations/{conversationId}/messages\n@desc List Messages\n@optional {page: map # Contains parameters for applying cursor pagination.}\n@returns(200) {messages: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}} # Ok\n@errors {404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}/conversations/{conversationId}/messages\n@desc Delete All Messages\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}/conversations/{conversationId}/messages/{messageId}\n@desc Delete Message\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/activity\n@desc Post Activity\n@returns(200) Ok\n@example_request {\"author\":{\"type\":\"user\",\"userId\":\"5963c0d619a30a2e00de36b8\"},\"type\":\"conversation:read\"}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/acceptControl\n@desc Accept Control\n@optional {metadata: any # Flat object containing custom properties. Strings, numbers and booleans are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size. The metadata object will be included in the `switchboard:acceptControl` and `switchboard:acceptControl:failure` webhooks.}\n@returns(200) Ok\n@errors {403: Forbidden, 404: Not found}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/offerControl\n@desc Offer Control\n@required {switchboardIntegration: str # The id or the name of the switchboard integration that will become pending. Also supports the `next` keyword to offer control to the next switchboard integration designated in the switchboard hierarchy configuration. This cannot match the active switchboard integration.}\n@optional {metadata: any # Flat object containing custom properties. Strings, numbers and booleans are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size. The metadata object will be included in the `switchboard:offerControl` and `switchboard:offerControl:failure` webhooks.}\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/passControl\n@desc Pass Control\n@required {switchboardIntegration: str # The id or the name of the switchboard integration that will become active. May also use the `next` keyword to transfer control to the next switchboard integration designated in the switchboard hierarchy configuration}\n@optional {metadata: any # Flat object containing custom properties. Strings, numbers and booleans are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size. The metadata object will be included in the `switchboard:passControl` webhook.}\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/releaseControl\n@desc Release Control\n@optional {metadata: any # Flat object containing custom properties. Strings, numbers and booleans are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size. The metadata object will be included in the `switchboard:releaseControl` webhook.}\n@returns(200) Ok\n@errors {403: Forbidden, 404: Not found}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/download\n@desc Download Message Ref\n@returns(200) Ok\n@example_request {\"userId\":\"6e416caac6a5e9544e3fb6d7\",\"apple\":{\"interactiveDataRef\":{\"url\":\"https://p61-content.icloud.com/M58C0A1A2EB62B6E899B4F28996E8DA229E1914295299C39944B2F2CA7482AE50.C01USN00\",\"bid\":\"com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.icloud.apps.messages.business.extension\",\"key\":\"00c0d1827fdc858fe7b42421de1fb289c2ee0a9463d787ce4f118506f970bd6e38\",\"signature\":\"81a619c81da5a01c6139219a5d20e17430c631e1eb\",\"owner\":\"M58C0A2A1EB62B4E859B4F28996E8DA229E1914295299C39944B2F2CA7482AE50.C01USN00\"}}}\n\n@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/conversionEvents\n@desc Post Conversion Events\n@returns(200) {conversionEvents: map{datasetId: str, eventsReceived: int}} # Ok\n@example_request {\"instagram\":{\"payload\":{\"data\":[{\"action_source\":\"business_messaging\",\"event_name\":\"TestEvent\",\"event_time\":1752161233,\"messaging_channel\":\"instagram\"}]}}}\n\n@endpoint POST /v2/apps/{appId}/integrations\n@desc Create Integration\n@required {type: str}\n@optional {id: str # The unique ID of the integration., status: str(inactive/active/error) # The status of the integration., displayName: str # A human-friendly name used to identify the integration.}\n@returns(201) Created\n@errors {400: Bad request}\n\n@endpoint GET /v2/apps/{appId}/integrations\n@desc List Integrations\n@optional {page: map # Contains parameters for applying cursor pagination., filter: map # Contains parameters for filtering the results.}\n@returns(200) {integrations: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}} # Ok\n@errors {400: Bad request}\n\n@endpoint GET /v2/apps/{appId}/integrations/{integrationId}\n@desc Get Integration\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint PATCH /v2/apps/{appId}/integrations/{integrationId}\n@desc Update Integration\n@returns(200) Ok\n@errors {404: Not found}\n@example_request {\"displayName\":\"My Test Integration\"}\n\n@endpoint DELETE /v2/apps/{appId}/integrations/{integrationId}\n@desc Delete Integration\n@returns(200) Ok\n@errors {400: Bad request, 404: Not found}\n\n@endpoint POST /v2/apps/{appId}/integrations/{integrationId}/keys\n@desc Create Integration Key\n@required {displayName: str # The name of the API key.}\n@returns(201) {key: map{id: str, displayName: any, secret: str}} # Created\n\n@endpoint GET /v2/apps/{appId}/integrations/{integrationId}/keys\n@desc List Integration Keys\n@returns(200) {keys: [map]} # Ok\n@errors {400: Bad request}\n\n@endpoint GET /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId}\n@desc Get Integration Key\n@returns(200) {key: map{id: str, displayName: any, secret: str}} # Ok\n\n@endpoint DELETE /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId}\n@desc Delete Integration Key\n@returns(200) Ok\n\n@endpoint POST /v2/apps/{appId}/integrations/{integrationId}/webhooks\n@desc Create Webhook\n@returns(201) {webhook: any} # Created\n@errors {400: Bad request, 403: Forbidden, 404: Not found}\n\n@endpoint GET /v2/apps/{appId}/integrations/{integrationId}/webhooks\n@desc List Webhooks\n@returns(200) {webhooks: [map]} # Ok\n@errors {403: Forbidden, 404: Not found}\n\n@endpoint GET /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}\n@desc Get Webhook\n@returns(200) {webhook: any} # Ok\n@errors {404: Not found}\n\n@endpoint PATCH /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}\n@desc Update Webhook\n@optional {target: str # URL to be called when the webhook is triggered., triggers: [str] # An array of triggers the integration is subscribed to. This property is case sensitive. [More details](https://developer.zendesk.com/api-reference/conversations/#section/Webhook-Triggers)., includeFullUser: bool=false # A boolean specifying whether webhook payloads should include the complete user schema for events involving a specific user., includeFullSource: bool=false # A boolean specifying whether webhook payloads should include the client and device object (when applicable).}\n@returns(200) {webhook: any} # Ok\n@errors {400: Bad request, 404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}\n@desc Delete Webhook\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/switchboards\n@desc Create Switchboard\n@returns(201) {switchboard: any} # Created\n@errors {400: Bad request, 404: Not found}\n\n@endpoint GET /v2/apps/{appId}/switchboards\n@desc List Switchboards\n@returns(200) {switchboards: [map]} # Ok\n@errors {404: Not found}\n\n@endpoint PATCH /v2/apps/{appId}/switchboards/{switchboardId}\n@desc Update Switchboard\n@optional {enabled: bool # Whether the switchboard is enabled. Allows creating the switchboard in a disabled state so that messages don't get lost or misrouted during switchboard configuration. When a switchboard is disabled, integrations linked to the switchboard will receive all events., defaultSwitchboardIntegrationId: str # The id of the switchboard integration that will be given control when a new conversation begins. It will also be used for conversations that existed before the switchboard was enabled. In some cases, the `defaultResponderId` of a specific integration will take precedence over this field. For more information, refer to the Switchboard guide.}\n@returns(200) {switchboard: any} # Ok\n@errors {404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}/switchboards/{switchboardId}\n@desc Delete Switchboard\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations\n@desc Create Switchboard Integration\n@required {name: str # Identifier for use in control transfer protocols. Restricted to alphanumeric characters, `-` and `_`.}\n@optional {integrationId: any # The id of the integration to link to the switchboard integration. Must be used when linking a custom integration. One of `integrationId` or `integrationType` must be provided., integrationType: any # The type of the integration to link to the switchboard integration. Must be used when linking an OAuth integration. One of `integrationId` or `integrationType` must be provided., deliverStandbyEvents: any=true, nextSwitchboardIntegrationId: str # The switchboard integration id to which control of a conversation is passed / offered by default., messageHistoryCount: int # Number of messages to include in the message history context.}\n@returns(201) {switchboardIntegration: any} # Created\n@errors {400: Bad request, 404: Not found}\n@example_request {\"name\":\"bot\",\"integrationType\":\"zd:agentWorkspace\",\"deliverStandbyEvents\":true,\"nextSwitchboardIntegrationId\":\"5ef21b86e933b7355c11c606\",\"messageHistoryCount\":5}\n\n@endpoint GET /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations\n@desc List Switchboard Integrations\n@returns(200) {switchboardIntegrations: [map]} # Ok\n@errors {404: Not found}\n\n@endpoint PATCH /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId}\n@desc Update Switchboard Integration\n@optional {name: str # Identifier for use in control transfer protocols. Restricted to alphanumeric characters, `-` and `_`., integrationId: any # The id of the integration to link to the switchboard integration. Must be used when linking a custom integration. Can't provide both `integrationId` and `integrationType`., integrationType: any # The type of the integration to link to the switchboard integration. Must be used when linking an OAuth integration. Can't provide both `integrationId` and `integrationType`., deliverStandbyEvents: bool # Setting to determine if webhooks should be sent when the switchboard integration is not in control of a conversation (standby status), nextSwitchboardIntegrationId: str # The switchboard integration id to which control of a conversation is passed / offered by default., messageHistoryCount: int # Number of messages to include in the message history context.}\n@returns(200) {switchboardIntegration: any} # Ok\n@errors {404: Not found}\n@example_request {\"deliverStandbyEvents\":true,\"nextSwitchboardIntegrationId\":\"5ef21b86e933b7355c11c606\",\"messageHistoryCount\":5}\n\n@endpoint DELETE /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId}\n@desc Delete Switchboard Integration\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/users\n@desc Create User\n@required {externalId: str # A unique identifier for the user. The `externalId` can be used to link a user to the same conversation [across multiple devices](https://developer.zendesk.com/documentation/conversations/messaging-platform/users/authenticating-users/).}\n@optional {signedUpAt: str # The date at which the user signed up. Must be ISO 8601 time format `YYYY-MM-DDThh:mm:ss.sssZ`., toBeRetained: bool # Flag indicating whether a user should be retained after they have passed their inactive expiry. See [creating deletion schedules for bot-only conversations](https://support.zendesk.com/hc/en-us/articles/8499219792154) for more information., profile: map{givenName: str, surname: str, email: str(email), avatarUrl: str(uri), locale: str} # Object hosting user profile information., metadata: map # Flat object containing custom properties. Strings, numbers and booleans  are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size.}\n@returns(201) {user: any} # Created\n@errors {409: Conflict}\n\n@endpoint GET /v2/apps/{appId}/users\n@desc List Users\n@required {filter: map # Contains parameters for filtering the results.}\n@returns(200) {users: [any]} # OK\n\n@endpoint GET /v2/apps/{appId}/users/{userIdOrExternalId}\n@desc Get User\n@returns(200) {user: any} # Ok\n@errors {404: Not found}\n\n@endpoint PATCH /v2/apps/{appId}/users/{userIdOrExternalId}\n@desc Update User\n@optional {signedUpAt: any, toBeRetained: any, profile: any, metadata: map # Flat object containing custom properties. Strings, numbers and booleans  are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size.}\n@returns(200) {user: any} # Ok\n@errors {404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}/users/{userIdOrExternalId}\n@desc Delete User\n@returns(200) Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/users/{userIdOrExternalId}/clients\n@desc Create Client\n@required {matchCriteria: any # The set of criteria used to determine the user's identity on a third-party channel., confirmation: map{type!: str, message: any} # The confirmation options of the link request., target: map{conversationId!: str} # The target conversation to attach the client to.}\n@returns(201) {client: map{id: str, type: str, status: str, integrationId: str?, externalId: str?, lastSeen: str?, linkedAt: str?, displayName: str?, avatarUrl: str(uri)?, info: map?, raw: map?}} # Created\n@example_request {\"matchCriteria\":{\"type\":\"whatsapp\",\"integrationId\":\"582dedf230e788746891281a\",\"primary\":true,\"phoneNumber\":\"+1 212-555-2368\"},\"confirmation\":{\"type\":\"immediate\"},\"target\":{\"conversationId\":\"029c31f25a21b47effd7be90\"}}\n\n@endpoint GET /v2/apps/{appId}/users/{userIdOrExternalId}/clients\n@desc List Clients\n@optional {page: map # Contains parameters for applying cursor pagination.}\n@returns(200) {clients: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}} # Ok\n@errors {400: Bad request}\n\n@endpoint DELETE /v2/apps/{appId}/users/{userIdOrExternalId}/clients/{clientId}\n@desc Remove Client\n@returns(200) Ok\n@errors {400: Bad request, 404: Not found}\n\n@endpoint GET /v2/apps/{appId}/users/{userIdOrExternalId}/devices\n@desc List Devices\n@returns(200) {devices: [map]} # Ok\n\n@endpoint GET /v2/apps/{appId}/users/{userIdOrExternalId}/devices/{deviceId}\n@desc Get Device\n@returns(200) {device: any} # Ok\n@errors {404: Not found}\n\n@endpoint DELETE /v2/apps/{appId}/users/{userIdOrExternalId}/personalinformation\n@desc Delete User Personal Information\n@returns(200) {user: any} # Ok\n@errors {404: Not found}\n\n@endpoint POST /v2/apps/{appId}/users/{zendeskId}/sync\n@desc Synchronize User\n@optional {survivingZendeskId: str # Only used for synchronizing messaging users when their Support user counterparts have been merged. The user.id of the surviving Support user is specified here.}\n@returns(200) {user: any} # Ok\n\n@endgroup\n\n@group tokenInfo\n@endpoint GET /v2/tokenInfo\n@desc Get Token Info\n@returns(200) {app: any} # Ok\n\n@endgroup\n\n@group oauth\n@endpoint GET /oauth/authorize\n@desc Authorize\n@required {client_id: str # Your integration’s unique identifier, response_type: str # For now the only acceptable value is code.}\n@optional {state: str # You may pass in any arbitrary string value here which will be returned to you along with the code via browser redirect., redirect_uri: str # 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.}\n@errors {302: Found}\n\n@endpoint POST /oauth/token\n@desc Get Token\n@required {code: str # The authorization code received via the OAuth flow, grant_type: str # Must be set to the string `authorization_code`, client_id: str # Your OAuth client ID, provisioned during the partner application process, client_secret: str # Your OAuth client secret, provisioned during the partner application process}\n@returns(200) {access_token: str, token_type: str} # Ok\n\n@endpoint DELETE /oauth/authorization\n@desc Revoke Access\n@returns(200) Ok\n\n@endgroup\n\n@end\n"}}