openapi: 3.0.2 info: version: 17.12.1 title: Sunshine Conversations API termsOfService: https://www.zendesk.com/company/customers-partners/master-subscription-agreement/ description: | # Introduction Welcome to the Sunshine Conversations API. The API allows you to craft entirely unique messaging experiences for your app and website as well as talk to any backend or external service. The Sunshine Conversations API is designed according to REST principles. The API accepts JSON in request bodies and requires that the `content-type: application/json` header be specified for all such requests. The API will always respond with an object. Depending on context, resources may be returned as single objects or as arrays of objects, nested within the response object. ## Regions Licensed Zendesk customers should use the following API host for all API requests, unless otherwise specified: ``` https://{subdomain}.zendesk.com/sc ``` For legacy Sunshine Conversations customers, see [regions](https://docs.smooch.io/guide/regions/) for the list of supported base URLs.

Note: When configuring an API host, make sure to always use https. Some API clients can have unexpected behaviour when following redirects from http to https.

## Errors Sunshine Conversations uses standard HTTP status codes to communicate errors. In general, a `2xx` status code indicates success while `4xx` indicates an error, in which case, the response body includes a JSON object which includes an array of errors, with a text `code` and `title` containing more details. Multiple errors can only be included in a `400 Bad Request`. A `5xx` status code indicates that something went wrong on our end. ```javascript { "errors": [ { "code": "unauthorized", "title": "Authorization is required" } ] } ``` ## API Version The latest version of the API is v2. Version v1.1 is still supported and you can continue using it but we encourage you to upgrade to the latest version. To learn more about API versioning at Sunshine Conversations, including instructions on how to upgrade to the latest version, [visit our docs](https://developer.zendesk.com/documentation/conversations/references/api-versioning/). ## API Pagination and Records Limits All paginated endpoints support cursor-based pagination. ### Cursor Pagination Cursor-based pagination is a common pagination strategy that avoids many of the pitfalls of offset–limit pagination. It works by returning a pointer to a specific item in the dataset. On subsequent requests, the server returns results after the given pointer. A `page[after]` or `page[before]` query string parameter may be provided, they are cursors pointing to a record id. The `page[after]` cursor indicates that only records **subsequent** to it should be returned. The `page[before]` cursor indicates that only records **preceding** it should be returned. **Only one** of `page[after]` or `page[before]` may be provided in a query, not both. In most endpoints, an optional `page[size]` query parameter may be passed to control the number of records returned by the request. ## API Libraries Sunshine Conversations provides an official API library for [Java](https://github.com/zendesk/sunshine-conversations-java), with more languages to come. These helpful libraries wrap calls to the API and can make interfacing with Sunshine Conversations easier. ## Postman Collection In addition to API libraries, Sunshine Conversations also has a Postman collection that can be used for development or testing purposes. See the [guide](https://developer.zendesk.com/documentation/conversations/references/openapi-specification/) for information on how to install and use the collection in your Postman client. ## Rate Limits Sunshine Conversations APIs are subject to rate limiting. If the rate limit is exceeded a `429 Too Many Requests` HTTP status code may be returned. We apply rate limits to prevent abuse, spam, denial-of-service attacks, and similar issues. Our goal is to keep the limits high enough so that any application using the platform as intended will not encounter them. However usage spikes do occur and encountering a rate limit may be unavoidable. In order to avoid production outages, you should implement `429` retry logic using exponential backoff and jitter. ## Conversation Size Limits Conversations are limited to 30,000 messages. Once you reach this maximum, a `423 Locked` HTTP status code is returned when trying to post a new message. To allow more messages to be sent to the affected conversation, you must [delete all messages](https://developer.zendesk.com/api-reference/conversations/#operation/DeleteAllMessages) to make room. ## Request Size Limits The Sunshine Conversations API imposes the following size limits on HTTP requests: | Request Type | Limit | | ------------ | ----- | | JSON | 100kb | | File upload | 50mb | ## Authorization This is an overview of how authorization works with the Sunshine Conversations API. Sunshine Conversations allows basic authentication or JSON Web Tokens (JWTs) as authentication methods for server-to-server calls. [See below](#section/Introduction/Authentication) for more details. There are three authorization scopes available for the v2 API: `integration`, `app`, and `account`. | Scope | Availability | Authorized Methods | | ----------- | ------------------------------------------- | ----------------------------------------------- | | account | Sunshine Conversations direct accounts only | All methods | | app | All account types | All methods besides Account Provisioning | | integration | All account types | Users, Conversations, Attachments, and Webhooks |

Note: An additional scope of user is used for authenticating users on the Zendesk Messaging SDKs. This scope, however, cannot be used with the v2 API.

## Authentication To authenticate requests to the API, you will need an API key, composed of a key id and a secret. For an overview of how authentication works in Sunshine Conversations and instructions on how to generate an API key, see [API authentication](https://developer.zendesk.com/documentation/conversations/getting-started/api-authentication/). API requests can be authenticated in two ways: - With Basic authentication you can make requests using an API key directly. - With JSON Web Tokens (JWTs) you sign tokens with an API key, which are then used to authenticate with the API. See [When to Use JWTs](https://developer.zendesk.com/documentation/conversations/getting-started/api-authentication/#when-to-use-jwts) to learn if JWTs are relevant for your usage. - Before using an API key in production, make sure to familiarize yourself with best practices on how to [securely handle credentials](https://developer.zendesk.com/documentation/conversations/getting-started/api-authentication/#secure-credential-handling). ### Basic Authentication API requests can be authenticated with [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) using an API key. The key id is used as the username and the secret as the password. The scope of access is determined by the owner of the API key. See the [guide](https://developer.zendesk.com/documentation/conversations/getting-started/api-authentication/#access-scopes) for more details. ### JWTs JSON Web Tokens (JWTs) are an industry standard authentication method. The full specification is described [here](https://tools.ietf.org/html/rfc7519), and a set of supported JWT libraries for a variety of languages and platforms can be found at http://jwt.io. To summarize, a JWT is composed of a header, a payload, and a signature. The payload contains information called claims which describe the subject to whom the token was issued. The JWT itself is transmitted via the HTTP `authorization` header. The token should be prefixed with “Bearer” followed by a space. For example: `Bearer your-jwt`. To generate a JWT, you need an API key, which is composed of a key ID and a secret. The key ID is included in a JWT’s header, as the `kid` property, while the secret is used to sign the JWT. For more in-depth coverage, see the [guide](https://developer.zendesk.com/documentation/conversations/getting-started/api-authentication/#jwt-authentication). #### Header The JWT header must contain the key id (kid) of the API key that is used to sign it. The algorithm (alg) used should be HS256. Unsigned JWTs are not accepted. ```javascript { "alg": "HS256", "typ": "JWT", "kid": "act_5963ceb97cde542d000dbdb1" } ``` #### Payload The JWT payload must include a scope claim which specifies the caller’s scope of access. - account-scoped JWTs must be generated with an API key associated with a Sunshine Conversations account (act*) or service account (svc*). ```javascript { "scope": "account" } ``` - app-scoped JWTs can be generated with an API key associated with an app (app\_). ```javascript { "scope": "app" } ``` x-logo: url: sunco_logo.svg altText: Sunshine Conversations href: https://developer.zendesk.com/documentation/conversations/ servers: - url: https://{subdomain}.zendesk.com/sc description: Your Zendesk subdomain - url: https://api.smooch.io description: United States server (for legacy Sunshine Conversations only) - url: https://api.eu-1.smooch.io description: European Union server (for legacy Sunshine Conversations only) security: - bearerAuth: - app - account - basicAuth: - app - account tags: - name: Apps x-displayName: Apps description: "If you're looking to enable messaging inside your product for your customers, with as much control over the experience as you'd like, you can create and control Sunshine Conversations apps programmatically using [Account Provisioning](https://docs.smooch.io/guide/intro-to-account-provisioning/).\n### Authentication\nAccount Provisioning endpoints require `account` scope. See the [authorization](#section/Introduction/Authorization) and [authentication](#section/Introduction/Authentication) sections for information.\nA user account API key (key id that starts with `act_`) can access all account provisioning routes. You can create an account key by going to your account page.\nA service account API key (key id that starts with `svc_`) may be used to manage apps, but not service accounts or service account keys.\n\n| Key Type | Authorized Methods |\n| -------------- | ----------------------------------------------------------------- |\n| act | All Core and Account Provisioning methods. |\n| svc \t | All Core methods, App Management methods, and App Keys methods. |\n\n### Service Accounts\nService Account schema and endpoints used for provisioning service accounts. A service account represents an API user, with its own set of credentials, that has only access to a certain subset of apps. For software makers that create apps on behalf of separate customers or businesses, service accounts can be used to generate and distribute credentials that only have access to a single business's data.\n\n### App settings\nApps have a number of optional settings that can be used to customize specific behaviors. See\nthe `settings` object described below for more information.\n" - name: App Keys x-displayName: App Keys description: This set of endpoints is used to provision and revoke API keys for a Sunshine Conversations app. An app can have a maximum of 10 keys. - name: Attachments x-displayName: Attachments description: | You can upload files of any type that can then be used to send a file, image or carousel message to a user. ## Attachments for Messages The attachments API allows you to upload a file for the purpose of sending a message. Using the for parameter, you can signal to Sunshine Conversations that your upload will be used to send a message to a user. Knowing this, Sunshine Conversations will safely delete the attachment when the message, conversation or user is deleted. x-zoas-docs: ignoreCanonicalSchema: true - name: Conversations x-displayName: Conversations description: A stored history of messages sent to and received from a `user`. This set of endpoints is used to provision and manage conversations. - name: Participants x-displayName: Participants description: Endpoints used for managing conversation [participants](https://developer.zendesk.com/documentation/conversations/getting-started/key-concepts/#participant). - name: Messages x-displayName: Messages description: Endpoints used for managing [messages](https://developer.zendesk.com/documentation/conversations/getting-started/key-concepts/#message). - name: Activities x-displayName: Activities description: Notify Sunshine Conversations of different conversation activities. x-zoas-docs: ignoreCanonicalSchema: true - name: Switchboard Actions x-displayName: Switchboard Actions description: Manage which switchboard integration has control over a conversation. x-zoas-docs: ignoreCanonicalSchema: true - name: Integrations x-displayName: Integrations description: | This set of endpoints is used to configure and manage various front-end messaging channels. - name: CustomIntegrationApiKeys x-displayName: Custom Integration API Keys description: This set of endpoints is used to provision and revoke API keys for a Sunshine Conversations integration. An integration can have a maximum of 10 keys. This endpoint is only available for integrations of type custom. An error will be returned when attempting to provision API keys for any other integration type. - name: Switchboards x-displayName: Switchboards description: Switchboard operations - name: Switchboard Integrations x-displayName: Switchboard Integrations description: Switchboard Integrations operations - name: Users x-displayName: Users description: This set of endpoints is used to manage users. - name: Clients x-displayName: Clients description: Endpoints used for provisioning [clients](https://developer.zendesk.com/documentation/conversations/getting-started/key-concepts/#client). - name: Devices x-displayName: Devices description: Endpoints used for fetching a user's [devices](https://developer.zendesk.com/documentation/conversations/getting-started/key-concepts/#device). - name: Webhooks description: | Endpoints for managing webhooks associated to a Sunshine Conversations Connect integration or a custom integration. Webhooks are a fantastic way to extend the Sunshine Conversations platform beyond the built-in feature set. You can use webhooks to build your own Sunshine Conversations chat clients, to integrate more deeply with your favorite CRM, or to build a bot. A webhook can only operate within the scope of a single Sunshine Conversations app. ## Webhook Triggers When a webhook trigger is triggered, a POST request will be made to the URL configured in your webhook object along with a JSON payload specific for the event type. | Trigger | Description | | ------------------------------------- | -------------------------------------------------------------------- | | client:add | When initiating a channel link or when an SDK client is created. | | client:remove | When a client is removed. This can happen when:
1. directly using the API
2. removing the client using the SDK
3. transferring a client due to a channel link
4. failing or cancelling a channel link | | client:update | When a client is updated. This can happen when:
1. a channel finds a user that matches the information provided
2. a client is activated
3. a user unsubscribes from a conversation or blocks the app | | conversation:create | When a new conversation is created. | | conversation:join | When a new participant joins a `sdkGroup` conversation. | | conversation:leave | When a participant leaves a `sdkGroup` conversation. | | conversation:remove | When a conversation is deleted. | | conversation:message | When a new message was sent in the conversation. | | conversation:message:delivery:channel | When a message is successfully delivered to a channel. | | conversation:message:delivery:failure | When a new message fails to be delivered in the conversation. | | conversation:message:delivery:user | When a new message is successfully delivered to a user. | | conversation:postback | When a user clicks on a postback action button. | | conversation:read | When a user has read the conversation. | | conversation:referral | When a user is referred to a conversation. See the conversation referrals guide for more details. | | passthrough:messaging | When a message is received with information that should be forwarded as-is. | | conversation:typing | When a user starts or stops typing. This trigger applies only to end users, not agents. | | switchboard:acceptControl | When a switchboard integration accepts control of a conversation. | | switchboard:acceptControl:failure | When control of a conversation fails to be accepted by a switchboard integration. | | switchboard:offerControl | When a switchboard integration has been offered control of the conversation. | | switchboard:offerControl:failure | When control of a conversation can't be offered to another switchboard integration. | | switchboard:passControl | When a switchboard integration gives control of the conversation to another switchboard integration. | | switchboard:passControl:failure | When changing a switchboard integration to active fails. | | switchboard:releaseControl | When a switchboard integration releases control of the conversation. | | user:merge | When two or more users are merged into one. | | user:update | When a user is updated. (Currently, when a user's identification is updated.)| | user:remove | When a user is deleted. | ## Securing Sunshine Conversations Webhooks When a webhook is created, a shared secret will be generated for it. The secret can be used to determine the veracity of a request to your webhook route. It is included as an `X-API-Key` header with each webhook request sent to the target URL. That secret is available in the response to the POST request used to generate the webhook, or through a GET request to the webhook route. ## Retry policy A webhook call will be attempted up to 5 times over a 15 minute window. The attempts will happen at an exponentially increasing interval if the target responds with anything but a success (2XX) or a [non-recoverable error](#non-recoverable-errors). If no response is received within 20 seconds, the call will be considered a failure and will also be reattempted. ### Non-recoverable Errors The following status codes are deemed to be non-recoverable and Sunshine Conversations will not reattempt a call when receiving a response with them: - 400: The target exists, but can’t process the payload. - 401: The target is behind authentication or doesn’t recognize the webhook secret. - 403: Sunshine Conversations should not be calling the target. - 404: The target doesn’t exist. - 406: The target exists, and rejected the webhook intentionally. - name: OAuth Endpoints x-displayName: OAuth description: "Endpoints used to power the OAuth flow for Zendesk Technology Partner integrations. Learn how to [build a marketplace bot](https://developer.zendesk.com/documentation/conversations/how-to-guides/building-a-marketplace-bot/) in the Zendesk developer docs.\n\nIssued access tokens use `integration` scope. The access token grants permission to get and create users and conversations associated with the connected app. The token also grants permission to create webhooks, however only webhooks created for the calling integration will be visible. An access token with integration scope cannot see or modify webhooks that were created by other integrations.\n\n| API\t | Access\t|\n| -------- | ------- |\n| [/v2/apps/:appId/users/\\*](#tag/Users)\t| Yes\t|\n| [/v2/apps/:appId/conversations/\\*](#tag/Conversations)\t| Yes\t|\n| [/v2/apps/:appId/integrations/me/webhooks/\\*](#tag/Webhooks)\t| Yes\t|\n| [/v2/apps/:appId/switchboards/\\*](#tag/Switchboards) | No |\n| [/v2/apps/\\*](#tag/Apps) | No |\n" x-zoas-docs: ignoreCanonicalSchema: true paths: /v2/apps: post: tags: - Apps summary: Create App operationId: CreateApp description: Creates a new app. When using [service account](#service-accounts) credentials, the service account is automatically granted access to the app. security: - basicAuth: - account - bearerAuth: - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/appCreateBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/appResponse' examples: default: $ref: '#/components/examples/createApp' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: should have required property 'displayName' '402': description: Payment required content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: payment_required title: Your account has reached the maximum number of apps for your subscription plan get: tags: - Apps summary: List Apps operationId: ListApps description: | Lists all apps that a user is part of. This API is paginated through [cursor pagination](#section/Introduction/API-Pagination-and-Records-Limits). ```shell /v2/apps?page[after]=5e1606762556d93e9c176f69&page[size]=10 ``` security: - basicAuth: - account - bearerAuth: - account parameters: - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/appFilterQuery' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/appListResponse' examples: default: $ref: '#/components/examples/listApps' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Invalid page query parameters '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: forbidden title: The serviceAccountId provided does not match supplied credentials /v2/apps/{appId}: parameters: - $ref: '#/components/parameters/appId' get: tags: - Apps summary: Get App operationId: GetApp description: Fetches an individual app. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/appResponseWithSubdomain' examples: default: $ref: '#/components/examples/getApp' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: app_not_found title: App not found patch: tags: - Apps summary: Update App operationId: UpdateApp description: Updates an app. security: - basicAuth: - app - account - bearerAuth: - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/appUpdateBody' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/appResponse' examples: default: $ref: '#/components/examples/updateApp' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: App metadata is limited to 4096 bytes in size. '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: app_not_found title: App not found delete: tags: - Apps summary: Delete App operationId: DeleteApp description: Removes the specified app, including all its enabled integrations. security: - basicAuth: - account - bearerAuth: - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: app_not_found title: App not found /v2/apps/{appId}/keys: parameters: - $ref: '#/components/parameters/appId' post: tags: - App Keys summary: Create App Key operationId: CreateAppKey description: | Creates an API key for the specified app. The response body will include a secret as well as its corresponding id, which you can use to generate JSON Web Tokens to securely make API calls on behalf of the app. security: - basicAuth: - account - bearerAuth: - account requestBody: required: true content: application/json: schema: type: object title: AppKeyCreateBody properties: displayName: allOf: - $ref: '#/components/schemas/displayName' nullable: false description: The name of the API key. example: Key 1 required: - displayName responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/appKeyResponse' examples: default: $ref: '#/components/examples/createAppKey' get: tags: - App Keys summary: List App Keys operationId: ListAppKeys description: Lists all API keys for a given app. security: - basicAuth: - account - bearerAuth: - account responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/appKeyListResponse' examples: default: $ref: '#/components/examples/listAppKeys' /v2/apps/{appId}/keys/{keyId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/keyId' get: tags: - App Keys summary: Get App Key operationId: GetAppKey description: Returns an API key. security: - basicAuth: - account - bearerAuth: - account responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/appKeyResponse' examples: default: $ref: '#/components/examples/getAppKey' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: not_found title: Resource not found delete: tags: - App Keys summary: Delete App Key operationId: DeleteAppKey description: Removes an API key. security: - basicAuth: - account - bearerAuth: - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: app_not_found title: App not found /v2/apps/{appId}/attachments: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/accessQuery' - $ref: '#/components/parameters/forQuery' - $ref: '#/components/parameters/conversationIdQuery' post: tags: - Attachments summary: Upload Attachment operationId: UploadAttachment description: | Upload an attachment to Sunshine Conversations to use in future messages. Files are uploaded using the multipart/form-data content type. Use the returned mediaUrl to send a file, image or carousel message. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/attachmentUploadBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/attachmentResponse' examples: default: $ref: '#/components/examples/uploadAttachment' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Bad request /v2/apps/{appId}/attachments/remove: parameters: - $ref: '#/components/parameters/appId' post: tags: - Attachments summary: Delete Attachment operationId: DeleteAttachment description: | Remove an attachment uploaded to Sunshine Conversations through the Upload attachment API. See [Attachments for Messages](#section/Attachments-for-Messages) to have attachments automatically deleted when deleting messages, conversations or users. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/attachmentDeleteBody' responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: 'Unsupported media URL for attachment deletion: https://badhost.com/image.png' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: not_found title: Attachment not found /v2/apps/{appId}/conversations: parameters: - $ref: '#/components/parameters/appId' post: tags: - Conversations summary: Create Conversation operationId: CreateConversation description: Create a conversation for the specified user(s). security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/conversationCreateBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/conversationResponse' examples: default: $ref: '#/components/examples/createConversation' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: app_not_found title: App not found get: tags: - Conversations summary: List Conversations operationId: ListConversations description: | Lists all conversations that a user is part of. This API is paginated through [cursor pagination](#section/Introduction/API-Pagination-and-Records-Limits). ```shell /v2/apps/:appId/conversations?filter[userId]=42589ad070d43be9b00ff7e5 ``` security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account parameters: - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/conversationFilterQuery' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/conversationListResponse' examples: default: $ref: '#/components/examples/listConversations' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Invalid page query parameters '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: user_not_found title: User not found /v2/apps/{appId}/conversations/{conversationId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' get: tags: - Conversations summary: Get Conversation operationId: GetConversation description: Fetches an individual conversation. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/conversationResponse' examples: default: $ref: '#/components/examples/getConversation' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found patch: tags: - Conversations summary: Update Conversation operationId: UpdateConversation description: Updates a conversation record. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/conversationUpdateBody' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/conversationResponse' examples: default: $ref: '#/components/examples/updateConversation' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found delete: tags: - Conversations summary: Delete Conversation operationId: DeleteConversation description: Delete an entire conversation record, along with its messages and attachments. Note that the default conversation cannot be deleted, but the messages contained [can be](#operation/DeleteAllMessages). security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Conversation c93bb9c14dde8ffb94564eae cannot be deleted because it is the default. '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/join: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Participants summary: Join Conversation operationId: JoinConversation description: | Adds a user to a conversation using either their userId or userExternalId. The endpoint only supports adding a participant to a sdkGroup conversation. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/participantJoinBody' examples: default: value: userId: 67a11490f0305f4a391e9f8a subscribeSDKClient: true responses: '201': description: Created content: application/json: schema: type: object title: ParticipantResponse description: The created participant. properties: participant: $ref: '#/components/schemas/participant' examples: default: $ref: '#/components/examples/joinConversation' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Too many participants '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/participants: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' get: tags: - Participants summary: List Participants operationId: ListParticipants description: | Lists all the participants of a particular conversation. This API is paginated through [cursor pagination](#section/Introduction/API-Pagination-and-Records-Limits). ```shell /v2/apps/:appId/conversations/:conversationId/participants?page[before]=26508c10541a4b0ff472e5e2 ``` security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account parameters: - $ref: '#/components/parameters/pageQuery' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/participantListResponse' examples: default: $ref: '#/components/examples/listParticipants' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Invalid page query parameters '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/leave: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Participants summary: Leave Conversation operationId: LeaveConversation description: | Removes a user from a conversation using either their userId, userExternalId, or participantId. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/participantLeaveBody' examples: default: value: userId: 67a11490f0305f4a391e9f8a responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: not_found title: User is not a member of the conversation /v2/apps/{appId}/conversations/{conversationId}/messages: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Messages summary: Post Message operationId: PostMessage description: Send a message in a particular conversation. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/messagePost' examples: default: $ref: '#/components/examples/text' text: $ref: '#/components/examples/text' carousel: $ref: '#/components/examples/carousel' file: $ref: '#/components/examples/file' form: $ref: '#/components/examples/form' image: $ref: '#/components/examples/image' list: $ref: '#/components/examples/list' location: $ref: '#/components/examples/location' whatsapp template: $ref: '#/components/examples/whatsappTemplate' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/messagePostResponse' examples: default: $ref: '#/components/examples/text-2' text: $ref: '#/components/examples/text-2' carousel: $ref: '#/components/examples/carousel-2' file: $ref: '#/components/examples/file-2' form: $ref: '#/components/examples/form-2' image: $ref: '#/components/examples/image-2' list: $ref: '#/components/examples/list-2' location: $ref: '#/components/examples/location-2' '423': description: | Message limit reached content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: locked title: Message limit of 30000 per conversation reached. get: tags: - Messages summary: List Messages operationId: ListMessages description: | List all messages for a particular conversation. This API is paginated through [cursor pagination](#section/Introduction/API-Pagination-and-Records-Limits), in the _backwards_ direction, with the most recent (i.e. last) page of messages being returned by default. The `hasMore` flag indicates whether more messages exist in the direction you are currently paginating through. To page backwards in the history, use the `beforeCursor` or follow the `prev` link. The page size limit is fixed at 100 messages per page. ```shell /v2/apps/:appId/conversations/:conversationId/messages?page[before]=5f32b88acf6bf25073b2be56 ``` security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account parameters: - $ref: '#/components/parameters/pageQuery' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/messageListResponse' examples: default: $ref: '#/components/examples/listMessages' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: not_found title: Resource not found delete: tags: - Messages summary: Delete All Messages operationId: DeleteAllMessages description: Delete all messages of a particular conversation. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/messages/{messageId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' - $ref: '#/components/parameters/messageId' delete: tags: - Messages summary: Delete Message operationId: DeleteMessage description: Delete a single message of a particular conversation. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/activity: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Activities summary: Post Activity operationId: PostActivity description: | Notify Sunshine Conversations of different conversation activities. Supported activity types are: * Typing activity * Conversation read event security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/activityPost' examples: default: value: author: type: user userId: 5963c0d619a30a2e00de36b8 type: conversation:read responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' /v2/apps/{appId}/conversations/{conversationId}/passControl: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Switchboard Actions summary: Pass Control operationId: PassControl description: The passControl action marks the selected switchboard integration as active and transitions all the other switchboard integrations to standby status. For information about the idempotency of this API, see the [switchboard guide](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/switchboard/#pass-control). security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/passControlBody' responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/releaseControl: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Switchboard Actions summary: Release Control operationId: ReleaseControl description: | The releaseControl action releases the control of the conversation by nullifying its switchboard state. For more information, see the [switchboard guide](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/switchboard/#release-control). When using integration auth scope, a 403 is returned if the authenticated integration is not currently active in the switchboard. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/releaseControlBody' responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: forbidden title: Forbidden '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/offerControl: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Switchboard Actions summary: Offer Control operationId: OfferControl description: The offerControl action will invite a switchboard integration to accept control of the conversation (changing its status to pending), and trigger a webhook signal to that integration indicating that they have been offered control of the conversation. Invalidates previous offerControl actions. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/offerControlBody' responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/acceptControl: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Switchboard Actions summary: Accept Control operationId: AcceptControl description: The acceptControl action transfers the control of the conversation to the pending switchboard integration. When using integration auth scope, a 403 is returned if the pending switchboard integration is not the authenticated integration. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/acceptControlBody' responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: forbidden title: Forbidden '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conversation_not_found title: Conversation not found /v2/apps/{appId}/conversations/{conversationId}/download: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Conversations summary: Download Message Ref operationId: DownloadMessageRef description: When a third party channel provides a reference of a data, this API can be used to download the reference and fetch the full data. Currently, only apple channel is supported. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/downloadMessageRefBody' examples: default: value: 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 responses: '200': description: Ok content: application/json: schema: type: object additionalProperties: true examples: default: $ref: '#/components/examples/emptyResponse' /v2/apps/{appId}/conversations/{conversationId}/conversionEvents: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/conversationId' post: tags: - Conversations summary: Post Conversion Events operationId: PostConversionEvents description: This API can be used to track your end user's interactions with third party channels. security: - basicAuth: - integration - app - account - bearerAuth: - integration - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/conversionEventsBody' examples: default: value: instagram: payload: data: - action_source: business_messaging event_name: TestEvent event_time: 1752161233 messaging_channel: instagram responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/conversionEventsResponse' examples: default: $ref: '#/components/examples/conversionEvents' /v2/apps/{appId}/integrations: parameters: - $ref: '#/components/parameters/appId' post: tags: - Integrations summary: Create Integration operationId: CreateIntegration description: The Create Integration endpoint allows you to provision apps with front-end messaging channels. Selecting a `custom` integration allows the creation of webhooks. security: - basicAuth: - app - account - bearerAuth: - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/integration' responses: '201': description: Created content: application/json: schema: allOf: - $ref: '#/components/schemas/integrationResponse' description: The created integration. examples: default: $ref: '#/components/examples/createIntegration' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Invalid integration type get: tags: - Integrations summary: List Integrations operationId: ListIntegrations description: | List available integrations. This API is paginated through [cursor pagination](#section/Introduction/API-Pagination-and-Records-Limits). ```shell /v2/apps/:appId/integrations?page[after]=5e1606762556d93e9c176f69&page[size]=10&filter[types]=custom,web ``` security: - basicAuth: - app - account - bearerAuth: - app - account parameters: - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/integrationFilterQuery' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/integrationListResponse' examples: default: $ref: '#/components/examples/listIntegrations' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Invalid query parameters /v2/apps/{appId}/integrations/{integrationId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/integrationId' get: tags: - Integrations summary: Get Integration operationId: GetIntegration description: Get integration. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: allOf: - $ref: '#/components/schemas/integrationResponse' description: The fetched integration. examples: default: $ref: '#/components/examples/getIntegration' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: integration_not_found title: Integration not found patch: tags: - Integrations summary: Update Integration operationId: UpdateIntegration description: Allows you to update certain fields of existing integrations. If updating a specific property is not supported, you must delete the integration and re-create it with the new data. security: - basicAuth: - app - account - bearerAuth: - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/integrationUpdate' examples: default: value: displayName: My Test Integration responses: '200': description: Ok content: application/json: schema: allOf: - $ref: '#/components/schemas/integrationResponse' description: The updated integration. examples: default: $ref: '#/components/examples/updateIntegration' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: integration_not_found title: Integration not found delete: tags: - Integrations summary: Delete Integration operationId: DeleteIntegration description: Delete the specified integration. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: SDK integrations configured on Admin Center cannot be deleted '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: integration_not_found title: Integration not found /v2/apps/{appId}/integrations/{integrationId}/keys: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/integrationId' post: tags: - CustomIntegrationApiKeys summary: Create Integration Key operationId: CreateCustomIntegrationKey description: Creates an API key for the specified custom integration. The response body will include a secret as well it’s corresponding id, which you can use to generate JSON Web Tokens to securely make API calls on behalf of the integration. security: - basicAuth: - app - account - bearerAuth: - app - account requestBody: required: true content: application/json: schema: type: object title: IntegrationApiKey properties: displayName: type: string description: The name of the API key. example: My custom key required: - displayName responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/integrationApiKeyResponse' examples: default: $ref: '#/components/examples/createIntegrationKey' get: tags: - CustomIntegrationApiKeys summary: List Integration Keys operationId: ListCustomIntegrationKeys description: Lists all API keys for a given integration. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: type: object title: IntegrationApiKeyListResponse properties: keys: type: array description: Integration keys of the supplied integration. items: $ref: '#/components/schemas/apiKey' examples: default: $ref: '#/components/examples/listIntegrationKeys' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: API keys are available only for custom integrations /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/integrationId' - $ref: '#/components/parameters/keyId' get: tags: - CustomIntegrationApiKeys summary: Get Integration Key operationId: GetCustomIntegrationKey description: Get the specified API key. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/integrationApiKeyResponse' examples: default: $ref: '#/components/examples/getIntegrationKey' delete: tags: - CustomIntegrationApiKeys summary: Delete Integration Key operationId: DeleteCustomIntegrationKey description: Removes an API key. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' /v2/apps/{appId}/integrations/{integrationId}/webhooks: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/integrationId' post: tags: - Webhooks summary: Create Webhook operationId: CreateWebhook description: Creates a new webhook associated with a Sunshine Conversations Connect integration or a custom integration. security: - basicAuth: - integration - app - bearerAuth: - integration - app requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/webhookCreateBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/webhookResponse' examples: default: $ref: '#/components/examples/createWebhook' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Bad request '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: forbidden title: Forbidden '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: integration_not_found title: Integration not found get: tags: - Webhooks summary: List Webhooks operationId: ListWebhooks description: Lists all webhooks for a given Sunshine Conversations Connect integration or custom integration. security: - basicAuth: - integration - app - bearerAuth: - integration - app responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/webhookListResponse' examples: default: $ref: '#/components/examples/listWebhooks' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: forbidden title: Forbidden '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: integration_not_found title: Integration not found /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/integrationId' - $ref: '#/components/parameters/webhookId' get: tags: - Webhooks summary: Get Webhook operationId: GetWebhook description: Gets the specified webhook associated with a Sunshine Conversations Connect integration or a custom integration. security: - basicAuth: - integration - app - bearerAuth: - integration - app responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/webhookResponse' examples: default: $ref: '#/components/examples/getWebhook' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: not_found title: Resource not found patch: tags: - Webhooks summary: Update Webhook operationId: UpdateWebhook description: Updates the specified webhook associated with a Sunshine Conversations Connect integration or a custom integration. security: - basicAuth: - integration - app - bearerAuth: - integration - app requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/webhookBody' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/webhookResponse' examples: default: $ref: '#/components/examples/updateWebhook' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Bad request '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: not_found title: Resource not found delete: tags: - Webhooks summary: Delete Webhook operationId: DeleteWebhook description: Deletes the specified webhook associated with a Sunshine Conversations Connect integration or a custom integration. security: - basicAuth: - integration - app - bearerAuth: - integration - app responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: not_found title: Resource not found /v2/apps/{appId}/switchboards: parameters: - $ref: '#/components/parameters/appId' post: tags: - Switchboards summary: Create Switchboard operationId: CreateSwitchboard description: Create a switchboard. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/switchboardResponse' examples: default: $ref: '#/components/examples/createSwitchboard' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Only one switchboard can be created per app '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: app_not_found title: App not found get: tags: - Switchboards summary: List Switchboards operationId: ListSwitchboards description: | Lists all switchboards belonging to the app. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/switchboardListResponse' examples: default: $ref: '#/components/examples/listSwitchboards' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: app_not_found title: App not found /v2/apps/{appId}/switchboards/{switchboardId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/switchboardId' patch: tags: - Switchboards summary: Update Switchboard operationId: UpdateSwitchboard description: Updates a switchboard record. security: - basicAuth: - app - account - bearerAuth: - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/switchboardUpdateBody' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/switchboardResponse' examples: default: $ref: '#/components/examples/updateSwitchboard' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: switchboard_not_found title: Switchboard not found delete: tags: - Switchboards summary: Delete Switchboard operationId: DeleteSwitchboard description: Deletes the switchboard and all its switchboard integrations. The integrations linked to these switchboard integrations are not deleted and will start receiving all conversation events. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: switchboard_not_found title: Switchboard not found /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/switchboardId' post: tags: - Switchboard Integrations summary: Create Switchboard Integration operationId: CreateSwitchboardIntegration description: Create a switchboard integration. security: - basicAuth: - app - account - bearerAuth: - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/switchboardIntegrationCreateBody' examples: default: value: name: bot integrationType: zd:agentWorkspace deliverStandbyEvents: true nextSwitchboardIntegrationId: 5ef21b86e933b7355c11c606 messageHistoryCount: 5 responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/switchboardIntegrationResponse' examples: default: $ref: '#/components/examples/createSwitchboardIntegration' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: too_many_switchboard_integrations title: Switchboard has reached the max number of switchboard integrations (10) '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: switchboard_not_found title: Switchboard not found get: tags: - Switchboard Integrations summary: List Switchboard Integrations operationId: ListSwitchboardIntegrations description: | Lists all switchboard integrations linked to the switchboard. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/switchboardIntegrationListResponse' examples: default: $ref: '#/components/examples/listSwitchboardIntegrations' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: switchboard_not_found title: Switchboard not found /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/switchboardId' - $ref: '#/components/parameters/switchboardIntegrationId' patch: tags: - Switchboard Integrations summary: Update Switchboard Integration operationId: UpdateSwitchboardIntegration description: Updates a switchboard integration record. security: - basicAuth: - app - account - bearerAuth: - app - account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/switchboardIntegrationUpdateBody' examples: default: value: deliverStandbyEvents: true nextSwitchboardIntegrationId: 5ef21b86e933b7355c11c606 messageHistoryCount: 5 responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/switchboardIntegrationResponse' examples: default: $ref: '#/components/examples/updateSwitchboardIntegration' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: switchboard_integration_not_found title: Enabled switchboard must have an associated default switchboardIntegration delete: tags: - Switchboard Integrations summary: Delete Switchboard Integration operationId: DeleteSwitchboardIntegration description: Deletes the switchboard integration. If the deleted switchboard integration had an active status for some conversations, the active switchboard integration will be re-selected following the default integration assignment rules to replace it next time the conversation has activity. Note that it is forbidden to delete a switchboard integration if it's the default one (a new one must be chosen first) or if another switchboard integration's `nextSwitchboardIntegrationId` refers to it. The integration that was linked to the deleted switchboard integration will start receiving all conversation events, regardless of the switchboard status. security: - basicAuth: - app - account - bearerAuth: - app - account responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: switchboard_integration_not_found title: SwitchboardIntegration not found /v2/apps/{appId}/users: parameters: - $ref: '#/components/parameters/appId' post: tags: - Users summary: Create User operationId: CreateUser description: Creates a new user. security: - basicAuth: - account - app - integration - bearerAuth: - account - app - integration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/userCreateBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/userResponse' examples: default: $ref: '#/components/examples/createUser' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: conflict title: User already exists get: tags: - Users summary: List Users operationId: ListUsers description: | Lists users by their email identity. The `identities.email` filter parameter is required, and it will match users based on emails found in the `identities` array. This endpoint will not match against emails stored in `profile.email`. ```shell /v2/apps/:appId/users?filter[identities.email]=sue@example.org ``` security: - basicAuth: - account - app - integration - bearerAuth: - account - app - integration parameters: - $ref: '#/components/parameters/userFilterQuery' - $ref: '#/components/parameters/brandIdQuery' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/userListResponse' examples: default: $ref: '#/components/examples/listUsers' /v2/apps/{appId}/users/{userIdOrExternalId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/userIdOrExternalId' - $ref: '#/components/parameters/brandIdQuery' get: tags: - Users summary: Get User operationId: GetUser description: Fetches an individual user. security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/userResponse' examples: default: $ref: '#/components/examples/getUser' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: user_not_found title: User not found patch: tags: - Users summary: Update User operationId: UpdateUser description: Updates a user. security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/userUpdateBody' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/userResponse' examples: default: $ref: '#/components/examples/updateUser' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: user_not_found title: User not found delete: tags: - Users summary: Delete User operationId: DeleteUser description: Delete a user, its clients and its conversation history. The user is considered completely deleted once the `user:delete` webhook is fired. To only delete a user’s personal information, see [Delete User Personal Information](#operation/DeleteUserPersonalInformation). security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: user_not_found title: User not found /v2/apps/{appId}/users/{userIdOrExternalId}/clients: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/userIdOrExternalId' - $ref: '#/components/parameters/brandIdQuery' post: tags: - Clients summary: Create Client operationId: CreateClient 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](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/channel-transfer/). security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/clientCreate' examples: default: $ref: '#/components/examples/whatsapp' mailgun: $ref: '#/components/examples/mailgun' messagebird: $ref: '#/components/examples/messagebird' twilio: $ref: '#/components/examples/twilio' whatsapp: $ref: '#/components/examples/whatsapp' responses: '201': description: Created content: application/json: schema: type: object title: ClientResponse properties: client: $ref: '#/components/schemas/client' examples: default: $ref: '#/components/examples/createClient' get: tags: - Clients summary: List Clients operationId: ListClients description: | Get all the clients for a particular user, including both linked clients and pending clients. This API is paginated through [cursor pagination](#section/Introduction/API-Pagination-and-Records-Limits). ```shell /v2/apps/:appId/users/:userId/clients?page[after]=5ebee0975ac5304b664a12fa ``` security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration parameters: - $ref: '#/components/parameters/pageQuery' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/clientListResponse' examples: default: $ref: '#/components/examples/listClients' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Invalid page query parameters /v2/apps/{appId}/users/{userIdOrExternalId}/clients/{clientId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/userIdOrExternalId' - $ref: '#/components/parameters/clientId' - $ref: '#/components/parameters/brandIdQuery' delete: tags: - Clients summary: Remove Client operationId: RemoveClient description: Remove a particular client and unsubscribe it from all connected conversations. security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: bad_request title: Cannot remove a client of type 'sdk' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: client_not_found title: Client not found /v2/apps/{appId}/users/{userIdOrExternalId}/devices: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/userIdOrExternalId' - $ref: '#/components/parameters/brandIdQuery' get: tags: - Devices summary: List Devices operationId: ListDevices description: | Get all the devices for a particular user. The Devices are sorted based on last seen time. security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/deviceListResponse' examples: default: $ref: '#/components/examples/listDevices' /v2/apps/{appId}/users/{userIdOrExternalId}/devices/{deviceId}: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/userIdOrExternalId' - $ref: '#/components/parameters/deviceId' - $ref: '#/components/parameters/brandIdQuery' get: tags: - Devices summary: Get Device operationId: GetDevice description: | Fetches a specific Device. security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/deviceResponse' examples: default: $ref: '#/components/examples/getDevice' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: device_not_found title: Device not found /v2/apps/{appId}/users/{userIdOrExternalId}/personalinformation: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/userIdOrExternalId' - $ref: '#/components/parameters/brandIdQuery' delete: tags: - Users summary: Delete User Personal Information operationId: DeleteUserPersonalInformation description: Delete a user’s personal information. Calling this API will clear `givenName`, `surname`, `email` and `avatarUrl` and every custom property for the specified user. For every client owned by the user, it will also clear `displayName`, `avatarUrl` and any channel specific information stored in the info and raw fields. Calling this API doesn’t delete the user’s conversation history. To fully delete the user, see [Delete User](#operation/DeleteUser). security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/userResponse' examples: default: $ref: '#/components/examples/deleteUserPersonalInformation' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errorResponse' examples: default: value: errors: - code: user_not_found title: User not found /v2/apps/{appId}/users/{zendeskId}/sync: parameters: - $ref: '#/components/parameters/appId' - $ref: '#/components/parameters/zendeskId' post: tags: - Users summary: Synchronize User operationId: SyncUser description: |- Synchronize a messaging user with its core Zendesk user counterpart. Messaging users are separate objects linked to a core Zendesk user record by `zendeskId`. It is possible for changes to be made to the core Zendesk user record in a way that causes the messaging user to fall out of sync. The core Zendesk user might have their primary email changed, for example. This endpoint can be used to update the messaging user with the `profile.givenName`, `profile.surname`, `externalId`, and primary email identity of its core Zendesk user counterpart.

It is also possible for two Zendesk users to be merged. In such a case, this API can be used to apply that merger on the messaging side. The surviving Zendesk user id can be specified via the `survivingZendeskId` parameter of the request body, and the outgoing `zendeskId` is specified in the request path.

Note: The Sunshine Conversations user must have a zendeskId. To populate this field, the user must be authenticated via the help center. For more information, see Manually synchronizing user data.

security: - basicAuth: - app - account - integration - bearerAuth: - app - account - integration requestBody: content: application/json: schema: $ref: '#/components/schemas/syncUserBody' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/userResponse' examples: default: $ref: '#/components/examples/syncUser' /v2/tokenInfo: get: tags: - OAuth Endpoints summary: Get Token Info operationId: GetTokenInfo 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. Use `oauth-bridge.zendesk.com/sc` as the base URL when invoking this endpoint. ``` GET https://oauth-bridge.zendesk.com/sc/v2/tokenInfo ``` security: [] responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/appResponseWithSubdomain' /oauth/authorize: get: tags: - OAuth Endpoints summary: Authorize operationId: 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. ``` https://oauth-bridge.zendesk.com/sc/oauth/authorize?response_type=code&client_id={client_id} ``` security: [] parameters: - $ref: '#/components/parameters/clientIdQuery' - $ref: '#/components/parameters/responseTypeQuery' - $ref: '#/components/parameters/stateQuery' - $ref: '#/components/parameters/redirectUriQuery' responses: '302': description: Found content: text/plain: schema: type: string example: Found. Redirecting to https://oauth-bridge.zendesk.com/oauth_bridge/start?response_type=code&client_id=some_id /oauth/token: post: tags: - OAuth Endpoints summary: Get Token operationId: GetToken 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. ``` POST https://oauth-bridge.zendesk.com/sc/oauth/token ``` security: [] requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: The authorization code received via the OAuth flow example: '658965' grant_type: type: string description: Must be set to the string `authorization_code` example: authorization_code client_id: type: string description: Your OAuth client ID, provisioned during the partner application process example: 5e4af71a81966cfff3ef6550 client_secret: type: string description: Your OAuth client secret, provisioned during the partner application process example: 5XJ85yjUtRcaQu_pDINblPZb required: - code - grant_type - client_id - client_secret responses: '200': description: Ok content: application/json: schema: properties: access_token: type: string description: An access token that can now be used to call Sunshine Conversations APIs. token_type: type: string description: Bearer. All issued tokens are of this type. examples: default: $ref: '#/components/examples/getToken' /oauth/authorization: delete: tags: - OAuth Endpoints summary: Revoke Access operationId: RevokeAccess description: | This endpoint is used to revoke your integration's access to the user's app. Revoking access means your integration will no longer be able to interact with the app, and any webhooks the integration had previously configured will be removed. Calling this endpoint is equivalent to the user removing your integration manually. Your integration's `removeUrl` (if configured) will also be called when an integration is removed in this way. security: - basicAuth: - integration - bearerAuth: - integration responses: '200': description: Ok content: application/json: schema: type: object examples: default: $ref: '#/components/examples/emptyResponse' x-webhooks: Webhook Event: post: tags: - Webhooks description: | A webhook payload contains an array of events, which may or may not originate from the same user or conversation. When processing webhook payloads, your application should take care to process each event in the array. summary: Webhook Events operationId: EventWebhooks requestBody: required: true content: application/json: schema: type: object properties: app: $ref: '#/components/schemas/appSubSchema' webhook: $ref: '#/components/schemas/webhookSubSchema' events: type: array description: The list of events that occurred. items: anyOf: - $ref: '#/components/schemas/clientAddEvent' - $ref: '#/components/schemas/clientRemoveEvent' - $ref: '#/components/schemas/clientUpdateEvent' - $ref: '#/components/schemas/conversationCreateEvent' - $ref: '#/components/schemas/conversationJoinEvent' - $ref: '#/components/schemas/conversationLeaveEvent' - $ref: '#/components/schemas/conversationRemoveEvent' - $ref: '#/components/schemas/conversationMessageDeliveryChannelEvent' - $ref: '#/components/schemas/conversationMessageDeliveryFailureEvent' - $ref: '#/components/schemas/conversationMessageDeliveryUserEvent' - $ref: '#/components/schemas/conversationMessageEvent' - $ref: '#/components/schemas/conversationPostbackEvent' - $ref: '#/components/schemas/conversationReadEvent' - $ref: '#/components/schemas/conversationReferralEvent' - $ref: '#/components/schemas/conversationTypingEvent' - $ref: '#/components/schemas/switchboardAcceptControl' - $ref: '#/components/schemas/switchboardAcceptControlFailure' - $ref: '#/components/schemas/switchboardOfferControl' - $ref: '#/components/schemas/switchboardOfferControlFailure' - $ref: '#/components/schemas/switchboardPassControl' - $ref: '#/components/schemas/switchboardPassControlFailure' - $ref: '#/components/schemas/switchboardReleaseControl' - $ref: '#/components/schemas/userMergeEvent' - $ref: '#/components/schemas/userUpdateEvent' - $ref: '#/components/schemas/userRemoveEvent' examples: client:add: $ref: '#/components/examples/clientAddEvent' client:remove: $ref: '#/components/examples/clientRemoveEvent' client:update: $ref: '#/components/examples/clientUpdateEvent' conversation:create: $ref: '#/components/examples/conversationCreateEvent' conversation:join: $ref: '#/components/examples/conversationJoinEvent' conversation:leave: $ref: '#/components/examples/conversationLeaveEvent' conversation:remove: $ref: '#/components/examples/conversationRemoveEvent' conversation:message:delivery:channel: $ref: '#/components/examples/conversationMessageDeliveryChannelEvent' conversation:message:delivery:failure: $ref: '#/components/examples/conversationMessageDeliveryFailureEvent' conversation:message:delivery:user: $ref: '#/components/examples/conversationMessageDeliveryUserEvent' conversation:message: $ref: '#/components/examples/conversationMessageEvent' conversation:postback: $ref: '#/components/examples/conversationPostbackEvent' conversation:read: $ref: '#/components/examples/conversationReadEvent' conversation:referral: $ref: '#/components/examples/conversationReferralEvent' conversation:typing: $ref: '#/components/examples/conversationTypingEvent' switchboard:acceptControl: $ref: '#/components/examples/switchboardAcceptControlEvent' switchboard:acceptControl:failure: $ref: '#/components/examples/switchboardAcceptControlFailureEvent' switchboard:offerControl: $ref: '#/components/examples/switchboardOfferControlEvent' switchboard:offerControl:failure: $ref: '#/components/examples/switchboardOfferControlFailureEvent' switchboard:passControl: $ref: '#/components/examples/switchboardPassControlEvent' switchboard:passControl:failure: $ref: '#/components/examples/switchboardPassControlFailureEvent' switchboard:releaseControl: $ref: '#/components/examples/switchboardReleaseControlEvent' user:merge: $ref: '#/components/examples/userMergeEvent' user:update: $ref: '#/components/examples/userUpdateEvent' user:remove: $ref: '#/components/examples/userRemoveEvent' responses: '200': description: Ok components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT basicAuth: type: http scheme: basic schemas: page: type: object properties: after: type: string description: | A record id. Results will only contain the records that come after the specified record. Only one of `after` or `before` can be provided, not both. example: 5e1606762556d93e9c176f69 minLength: 24 maxLength: 24 before: type: string description: | A record id. Results will only contain the records that come before the specified record. Only one of `after` or `before` can be provided, not both. example: 5e1606762556d93e9c176f69 minLength: 24 maxLength: 24 size: type: integer description: The number of records to return. Does not apply to the `listMessages` endpoint. default: 25 example: 10 minimum: 1 maximum: 100 displayName: type: string nullable: true minLength: 1 maxLength: 100 appSettings: type: object description: Customizable app settings. properties: conversationRetentionSeconds: type: integer description: | Number of seconds of inactivity before a conversation’s messages will be automatically deleted. See [Conversation Retention Seconds](https://docs.smooch.io/guide/creating-and-managing-apps/#conversation-retention-seconds) for more information. minimum: 0 maskCreditCardNumbers: type: boolean description: | A boolean specifying whether credit card numbers should be masked when sent through Sunshine Conversations. useAnimalNames: type: boolean description: | A boolean specifying whether animal names should be used for unnamed users. See the [user naming guide](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/receiving-messages/#message-author-name) for details. echoPostback: type: boolean description: | A boolean specifying whether a message should be added to the conversation history when a postback button is clicked. See [Echo Postbacks](https://docs.smooch.io/guide/creating-and-managing-apps/#echo-postbacks) for more information. ignoreAutoConversationStart: type: boolean description: | A boolean specifying whether a non message event coming from a channel will trigger a [start conversation](https://developer.zendesk.com/api-reference/conversations/#section/Webhook-Triggers) event and count as a monthly active user (MAU).

Note: Calling startConversation() (or equivalent) from the Android, iOS or Web SDK will count as a MAU, regardless of the value of this setting.

multiConvoEnabled: type: boolean description: | A boolean specifying whether users are allowed to be part of several conversations. Enabling `multiConvo` is **irreversible**. example: true appLocalizationEnabled: type: boolean description: | A boolean specifying whether the messages authored by the Sunshine Conversations platform should be localized. endSessionEnabled: type: boolean description: | A boolean specifying whether users can manually end (close) their conversation session via an "End Session" button on SDK.

Note: multiConvo is required to enable

disableConversationReopen: type: boolean description: | A boolean specifying whether users can reopen conversations that have been ended.

Note: multiConvo is required to enable

metadata: type: object nullable: true description: | 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. additionalProperties: true example: lang: en-ca app: type: object x-resourceId: Apps properties: id: type: string description: A canonical ID that can be used to retrieve the Sunshine Conversations app. example: 5d8cff3cd55b040010928b5b displayName: allOf: - $ref: '#/components/schemas/displayName' description: The friendly name of the app. example: My App settings: $ref: '#/components/schemas/appSettings' metadata: $ref: '#/components/schemas/metadata' meta: type: object description: Response metadata. properties: hasMore: type: boolean description: A flag that indicates if there are more records that can be fetched. afterCursor: type: string description: | A record id that can be used as a `page[after]` parameter in a new request to get the next page. Not specified if there are no subsequent pages. example: 55c8d9758590aa1900b9b9f6 beforeCursor: type: string description: | A record id that can be used as a `page[before]` parameter in a new request to get the previous page. Not specified if there are no previous pages. example: 55c8d9758590aa1900b9b9f6 links: type: object description: Previous and next page links, if they exist. properties: prev: type: string description: A link to the previous page. Not specified if there are no previous pages. example: https://{subdomain}.zendesk.com/sc/v2/apps?page[before]=fcafad804c39a39648004af9 next: type: string description: A link to the next page. Not specified if there are no subsequent pages. example: https://{subdomain}.zendesk.com/sc/v2/apps?page[after]=5ea868f862cdd24abf010b38 appListResponse: type: object properties: apps: type: array description: List of returned apps. items: $ref: '#/components/schemas/app' meta: $ref: '#/components/schemas/meta' links: $ref: '#/components/schemas/links' error: type: object properties: code: type: string description: Error code used for classifying similar error types example: not_found title: type: string description: Description of the error example: Resource not found errorResponse: type: object properties: errors: type: array description: List of errors that occurred. items: $ref: '#/components/schemas/error' appCreateBody: type: object title: AppCreateBody properties: displayName: allOf: - $ref: '#/components/schemas/displayName' nullable: false description: The friendly name of the app. example: My App settings: $ref: '#/components/schemas/appSettings' metadata: $ref: '#/components/schemas/metadata' required: - displayName appResponse: type: object title: AppResponse properties: app: allOf: - $ref: '#/components/schemas/app' description: The app. appSubdomain: type: object x-resourceId: Apps properties: subdomain: type: string description: The subdomain of the app. example: test-domain appResponseWithSubdomain: type: object title: AppResponse properties: app: allOf: - $ref: '#/components/schemas/app' - $ref: '#/components/schemas/appSubdomain' description: The app. appUpdateBody: type: object properties: displayName: allOf: - $ref: '#/components/schemas/displayName' nullable: false description: The friendly name of the app. example: My App settings: $ref: '#/components/schemas/appSettings' metadata: $ref: '#/components/schemas/metadata' appKey: type: object x-resourceId: App Keys properties: id: type: string description: The unique ID of the API key, used when signing JWTs or accessing the API using Basic Authentication. example: app_5723a347f82ba0516cb4ea34 displayName: type: string description: The name of the API key. example: Key 1 secret: type: string description: The secret of the API key, used when signing JWTs or accessing the API using Basic Authentication example: 5XJ85yjUtRcaQu_pDINblPZb appKeyListResponse: type: object properties: keys: type: array description: List of returned keys. items: $ref: '#/components/schemas/appKey' appKeyResponse: type: object title: AppKeyResponse properties: key: allOf: - $ref: '#/components/schemas/appKey' description: The created key object. attachmentUploadBody: type: object properties: source: type: string format: binary required: - source attachmentSchema: type: object properties: mediaUrl: type: string description: | Uploaded attachment’s url. example: https://smooch.io/rocks.smooch.media-dev/apps/5ec41c54fe13cc5ac404bedc/conversations/c616a583e4c240a871818541/TmYMVQUBNsQRItX4fKf4aC-T/Screen%20Shot%202020-09-02%20at%204.04.41%20PM.png mediaType: type: string description: Uploaded attachment's media type example: image/png attachmentResponse: type: object title: AttachmentResponse properties: attachment: allOf: - $ref: '#/components/schemas/attachmentSchema' description: The uploaded attachment object. attachmentDeleteBody: type: object properties: mediaUrl: type: string description: The media URL used for a file or image message. example: https://s3.amazonaws.com/document.pdf required: - mediaUrl conversationType: type: string description: The type of the conversation. enum: - personal - sdkGroup example: personal name: type: string description: Identifier for use in control transfer protocols. Restricted to alphanumeric characters, `-` and `_`. maxLength: 128 example: bot switchboardIntegrationId: type: string description: Id of the integration that should deliver events routed by the switchboard. example: 5ef21b86e933b7355c11c605 switchboardIntegrationType: type: string description: Type of integration that should deliver events routed by the switchboard. If referencing an OAuth integration, the clientId issued by Sunshine Conversations during the OAuth partnership process will be the value of integrationType. example: zd:agentWorkspace switchboardIntegrationWebhook: type: object properties: id: type: string description: The unique ID of the switchboard integration. example: 5ef21b86e933b7355c11c604 name: $ref: '#/components/schemas/name' integrationId: $ref: '#/components/schemas/switchboardIntegrationId' integrationType: $ref: '#/components/schemas/switchboardIntegrationType' conversationTruncated: type: object properties: id: type: string description: The unique ID of the conversation. example: c93bb9c14dde8ffb94564eae type: $ref: '#/components/schemas/conversationType' metadata: $ref: '#/components/schemas/metadata' activeSwitchboardIntegration: allOf: - $ref: '#/components/schemas/switchboardIntegrationWebhook' description: The current switchboard integration that is in control of the conversation. This field is omitted if no `activeSwitchboardIntegration` exists for the conversation. nullable: true pendingSwitchboardIntegration: allOf: - $ref: '#/components/schemas/switchboardIntegrationWebhook' description: The switchboard integration that is awaiting control. This field is omitted if no switchboard integration has been previously offered control. nullable: true description: type: string nullable: true minLength: 1 maxLength: 100 description: A short text describing the conversation. example: Conversation between Rogers and Carl. icon: type: string nullable: true format: uri minLength: 1 maxLength: 2048 description: A custom conversation icon url. The image must be in either JPG, PNG, or GIF format example: https://www.gravatar.com/image.jpg conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' - type: object x-resourceId: Conversations properties: isDefault: type: boolean description: | Whether the conversation is the default conversation for the user. Will be true for the first personal conversation created for the user, and false in all other cases. example: false displayName: allOf: - $ref: '#/components/schemas/displayName' description: | A friendly name for the conversation, may be displayed to the business or the user. example: My conversation description: $ref: '#/components/schemas/description' iconUrl: $ref: '#/components/schemas/icon' businessLastRead: type: string description: | A datetime string with the format YYYY-MM-DDThh:mm:ss.SSSZ representing the moment the conversation was last marked as read with role business. nullable: true example: '2020-06-23T14:33:47.492Z' lastUpdatedAt: type: string description: | A datetime string with the format YYYY-MM-DDThh:mm:ss.SSSZ representing the moment the last message was received in the conversation, or the creation time if no messages have been received yet. nullable: true example: '2020-06-26T14:33:47.120Z' createdAt: type: string description: | A datetime string with the format YYYY-MM-DDThh:mm:ss.SSSZ representing the creation time of the conversation. example: '2020-06-20T11:26:07.001Z' conversationListResponse: type: object properties: conversations: type: array description: List of returned conversations. items: $ref: '#/components/schemas/conversation' meta: $ref: '#/components/schemas/meta' links: $ref: '#/components/schemas/links' participantSubSchema: anyOf: - type: object title: ParticipantWithUserId properties: userId: type: string description: The id of the user that will be participating in the conversation. It will return `404` if the user can’t be found. One of `userId` or `userExternalId` is required, but not both. example: 42589ad070d43be9b00ff7e5 subscribeSDKClient: description: When passed as true, the SDK client of the concerned participant will be subscribed to the conversation. The user will start receiving push notifications for this conversation right away, without having to view the conversation on the SDK beforehand. An SDK client will be created for users that don’t already have one. This field is required if the conversation is of type `sdkGroup`. type: boolean example: false - type: object title: ParticipantWithUserExternalId properties: userExternalId: type: string description: The `externalId` of the user that will be participating in the conversation. It will return `404` if the user can’t be found. One of `userId` or `userExternalId` is required, but not both. example: your-own-user-id subscribeSDKClient: description: When passed as true, the SDK client of the concerned participant will be subscribed to the conversation. The user will start receiving push notifications for this conversation right away, without having to view the conversation on the SDK beforehand. An SDK client will be created for users that don’t already have one. This field is required if the conversation is of type `sdkGroup`. type: boolean example: false conversationCreateBody: type: object title: ConversationCreateBody properties: type: $ref: '#/components/schemas/conversationType' participants: type: array description: | 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`. items: $ref: '#/components/schemas/participantSubSchema' maxItems: 10 displayName: allOf: - $ref: '#/components/schemas/displayName' description: | A friendly name for the conversation, may be displayed to the business or the user. example: My conversation description: $ref: '#/components/schemas/description' iconUrl: $ref: '#/components/schemas/icon' metadata: $ref: '#/components/schemas/metadata' required: - type conversationResponse: type: object title: ConversationResponse properties: conversation: allOf: - $ref: '#/components/schemas/conversation' description: The conversation. conversationUpdateBody: type: object properties: displayName: allOf: - $ref: '#/components/schemas/displayName' description: | A friendly name for the conversation, may be displayed to the business or the user. example: My conversation description: $ref: '#/components/schemas/description' iconUrl: $ref: '#/components/schemas/icon' metadata: $ref: '#/components/schemas/metadata' participantJoinBody: allOf: - $ref: '#/components/schemas/participantSubSchema' clientType: type: string description: The type of integration that the client represents. Can be any of the supported integration types, or sdk for integrations of type ios, android, unity and web. enum: - apple - gbm - googlercs - instagram - kakao - line - mailgun - messagebird - messenger - slackconnect - sdk - telegram - twilio - twitter - viber - wechat - whatsapp example: telegram clientAssociation: type: object properties: type: $ref: '#/components/schemas/clientType' clientId: type: string description: The id of the client being referenced. example: 42589ad070d43be9b00ff7e5 participant: type: object x-resourceId: Participants properties: id: type: string description: The unique ID of the participant. example: c93bb9c14dde8ffb94564eae userId: type: string description: The id of the associated user. example: 42589ad070d43be9b00ff7e5 unreadCount: type: integer description: Number of messages the user has not yet read. example: 0 clientAssociations: type: array description: | Represents the clients that are active in the conversation for a particular user. A participant can have multiple clientAssociations in the case of channel transfer, business initiated conversations, or identified users. The order of the array indicates how recently a client has interacted with the conversation, with the most recent client first. The first item in the array is considered to be the user's primary client for that conversation, and will be selected first for message delivery. items: $ref: '#/components/schemas/clientAssociation' userExternalId: type: string description: The externalId of the associated user. example: your-own-id nullable: true lastRead: type: string description: A datetime string with the format YYYY-MM-DDThh:mm:ss.SSSZ representing the latest message the user has read. example: '2019-01-14T18:55:12.515Z' nullable: true participantListResponse: type: object description: List of returned participants. properties: participants: type: array items: $ref: '#/components/schemas/participant' meta: $ref: '#/components/schemas/meta' links: $ref: '#/components/schemas/links' participantLeaveBody: oneOf: - type: object title: ParticipantLeaveBodyUserId properties: userId: type: string description: | The id of the user that will be removed from the conversation. It will return 404 if the user can’t be found. example: 42589ad070d43be9b00ff7e5 - type: object title: ParticipantLeaveBodyUserExternalId properties: userExternalId: type: string description: | The externalId of the user that will be removed from the conversation. It will return 404 if the user can’t be found. example: your-own-user-id - type: object title: ParticipantLeaveBodyParticipantId properties: participantId: type: string description: | The participantId of the user that will be removed from the conversation. It will return 404 if the user can’t be found. example: 42589ad070d43be9b00ff7e5 author: type: object description: The author of the message. properties: type: type: string description: | The author type. Either "user" (representing the end user) or "business" (sent on behalf of the business). enum: - business - user example: business subtypes: type: array description: | A string array that indicates the author's subtypes. Messages from "business" type with an "AI" subtype are generated by AI and a disclaimer is appended to the text of the message sent to the customer. For third-party channels, the disclaimer is applied for image, file, and text message types. Message with an "activity" subtype are generated by system activities. Message with an "agent" subtype are generated by human agents (available in responses only). Message with a "bot" subtype are generated by bot agents (available in responses only). items: type: string enum: - AI - activity - agent - bot uniqueItems: true minItems: 1 maxItems: 1 userId: type: string description: The id of the user. Only supported when `type` is user. example: 5963c0d619a30a2e00de36b8 userExternalId: type: string description: The externalId of the user. Only supported when `type` is user. writeOnly: true example: your-own-id brandId: type: string nullable: true minLength: 1 maxLength: 24 description: | The brandId of the user. Required when `userExternalId` is used and the target user is brand-separated, and should be omitted otherwise. example: '9477922990333' writeOnly: true displayName: type: string description: The display name of the message author. example: Steve avatarUrl: allOf: - $ref: '#/components/schemas/icon' nullable: false description: A custom message icon URL. The image must be JPG, PNG, or GIF format. required: - type ticketClosed: type: object properties: type: type: string enum: - ticket:closed description: The type of system activity that generated the message. The value of this field determines the dynamic content that is rendered to the end-user / agent when viewing this message. Each `type` value will have a set of pre-defined, localized strings that describe the activity. default: ticket:closed data: type: object description: No additional data is supplied with the "ticket:closed" activity type at this time. additionalProperties: true required: - type readOnly: true transferToEmail: type: object properties: type: type: string enum: - ticket:transfer:email description: The type of system activity that generated the message. The value of this field determines the dynamic content that is rendered to the end-user / agent when viewing this message. Each `type` value will have a set of pre-defined, localized strings that describe the activity. default: ticket:transfer:email data: type: object description: No additional data is supplied with the "ticket:transfer:email" activity type at this time. additionalProperties: true required: - type readOnly: true endedByUser: type: object properties: type: type: string enum: - conversation:endedByUser description: The type of system activity that generated the message. The value of this field determines the dynamic content that is rendered to the end-user / agent when viewing this message. Each `type` value will have a set of pre-defined, localized strings that describe the activity. default: conversation:endedByUser data: type: object description: No additional data is supplied with the "conversation:endedByUser" activity type at this time. additionalProperties: true required: - type readOnly: true activityMessage: oneOf: - $ref: '#/components/schemas/ticketClosed' - $ref: '#/components/schemas/transferToEmail' - $ref: '#/components/schemas/endedByUser' discriminator: propertyName: type mapping: ticket:closed: '#/components/schemas/ticketClosed' ticket:transfer:email: '#/components/schemas/transferToEmail' conversation:endedByUser: '#/components/schemas/endedByUser' htmlText: type: string description: |- HTML text content of the message. Can be provided in place of `text`. Cannot be used with `markdownText`. If no `text` is provided, will be converted to `text` upon reception to be displayed on channels that do not support rich text. See [rich text](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/structured-messages/#rich-text) documentation for more information. maxLength: 4096 example:

Hello!

markdownText: type: string writeOnly: true description: |- Markdown text content of the message. Can be provided in place of `text`. Cannot be used with `htmlText`. Will be converted to `htmlText` upon reception. If converted `htmlText` exceeds 4096 characters, the message will be rejected. If no `text` is provided, will be converted to `text` upon reception to be displayed on channels that do not support rich text. See [rich text](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/structured-messages/#rich-text) documentation for more information. maxLength: 4096 example: '# Hello!' buy: type: object properties: type: type: string description: The type of action. default: buy text: type: string description: The button text. example: Buy vinegar amount: type: integer description: The amount being charged. It needs to be specified in cents and is an integer (9.99$ -> 999). example: 8000 currency: type: string description: An ISO 4217 standard currency code in lowercase. Used for actions of type buy. example: CAD metadata: $ref: '#/components/schemas/metadata' required: - text - type - amount extraChannelOptions: type: object description: Extra options to pass directly to the channel API. properties: messenger: type: object description: Messenger channel options. properties: messenger_extensions: type: boolean description: For webview type actions, a boolean value indicating whether the URL should be loaded with Messenger Extensions enabled. [More info](https://developers.facebook.com/docs/messenger-platform/send-api-reference/url-button). default: false example: false webview_share_button: type: string description: For webview type actions, a string value indicating if the share button should be hidden. [More Info](https://developers.facebook.com/docs/messenger-platform/reference/buttons/url). enum: - hide link: type: object description: A link action will open the provided URI when tapped. properties: type: type: string description: The type of action. default: link uri: type: string description: The action URI. This is the link that will be used in the clients when clicking the button. text: type: string description: The button text. default: type: boolean description: Boolean value indicating whether the action is the default action for a message item in Facebook Messenger. metadata: $ref: '#/components/schemas/metadata' extraChannelOptions: $ref: '#/components/schemas/extraChannelOptions' required: - text - type - uri locationRequest: type: object description: A location request action will prompt the user to share their location. properties: type: type: string description: The type of action. default: locationRequest text: type: string description: The button text. metadata: $ref: '#/components/schemas/metadata' required: - text - type postback: type: object properties: type: type: string description: The type of action. default: postback text: type: string description: The button text. payload: type: string description: The payload of a postback or reply button. metadata: $ref: '#/components/schemas/metadata' required: - text - type - payload reply: type: object properties: type: type: string description: The type of action. text: type: string description: The button text. We recommend a non-empty value because some channels may not support empty ones. Text longer than 20 characters will be truncated on Facebook Messenger, and longer than 40 characters will be truncated on Web Messenger, iOS, and Android. payload: type: string description: A string payload to help you identify the action context. Used when posting the reply. You can also use metadata for more complex needs. metadata: $ref: '#/components/schemas/metadata' iconUrl: type: string description: An icon to render next to the reply option. required: - text - type - payload webview: type: object description: When a webview actions is clicked/tapped, the provided URI will be loaded in a webview. Channels that do not support webviews will open the fallback URI instead. properties: type: type: string description: The type of action. uri: type: string description: The webview URI. This is the URI that will open in the webview when clicking the button. text: type: string description: The button text. default: type: boolean description: Boolean value indicating whether the action is the default action for a message item in Facebook Messenger. metadata: $ref: '#/components/schemas/metadata' extraChannelOptions: $ref: '#/components/schemas/extraChannelOptions' size: type: string enum: - compact - tall - full description: The size to display a webview. Used for actions of type webview. fallback: type: string description: The fallback uri for channels that don’t support webviews. Used for actions of type webview. openOnReceive: type: boolean description: Boolean value indicating if the webview should open automatically. Only one action per message can be set to true. Currently only supported on the Web Messenger. required: - text - type - uri - fallback action: oneOf: - $ref: '#/components/schemas/buy' - $ref: '#/components/schemas/link' - $ref: '#/components/schemas/locationRequest' - $ref: '#/components/schemas/postback' - $ref: '#/components/schemas/reply' - $ref: '#/components/schemas/webview' discriminator: propertyName: type textMessage: type: object properties: type: type: string description: The type of message. default: text text: type: string description: The text content of the message. Required unless `actions`, `htmlText` or `markdownText` is provided. maxLength: 4096 example: Hello! htmlText: $ref: '#/components/schemas/htmlText' blockChatInput: type: boolean description: When set to true, the chat input will be disabled on supported client implementations when the message is the most recent one in the history. Can be used for guided flows or to temporarily disable the user's ability to send messages in the conversation. markdownText: $ref: '#/components/schemas/markdownText' actions: type: array description: Array of message actions. items: $ref: '#/components/schemas/action' payload: type: string description: The payload of a [reply button](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/structured-messages/#reply-buttons) response message. required: - type actionSubset: oneOf: - $ref: '#/components/schemas/buy' - $ref: '#/components/schemas/link' - $ref: '#/components/schemas/postback' - $ref: '#/components/schemas/webview' discriminator: propertyName: type item: type: object properties: title: type: string description: The title of the item. minLength: 1 maxLength: 128 description: type: string description: The description of the item. maxLength: 128 mediaUrl: type: string format: uri description: The image url attached to the item. maxLength: 2048 mediaType: type: string description: The MIME type for any image attached in the mediaUrl. maxLength: 128 altText: type: string maxLength: 128 description: An optional description of the media for accessibility purposes. The field will be saved by default with the file name as the value. size: type: string description: The size of the image. enum: - compact - large actions: type: array description: An array of objects representing the actions associated with the item. items: $ref: '#/components/schemas/actionSubset' minItems: 1 maxItems: 3 metadata: $ref: '#/components/schemas/metadata' required: - title - actions carouselMessage: type: object description: Carousel messages are a horizontally scrollable set of items that may each contain text, an image, and message actions. Not all messaging channels fully support carousel messages; currently only Facebook Messenger, LINE, Telegram, Viber, the Web Messenger, the Android SDK and the iOS SDK cover the full functionality. For all other platforms a carousel message is rendered as raw text. The raw text fallback does not include any images or postback message actions. properties: type: type: string description: The type of message. default: carousel text: type: string description: The fallback text message used when carousel messages are not supported by the channel. readOnly: true blockChatInput: type: boolean description: When set to true, the chat input will be disabled on supported client implementations when the message is the most recent one in the history. Can be used for guided flows or to temporarily disable the user's ability to send messages in the conversation. items: type: array description: An array of objects representing the items associated with the message. Only present in carousel and list type messages. items: $ref: '#/components/schemas/item' minItems: 1 maxItems: 10 displaySettings: type: object description: Settings to adjust the carousel layout. properties: imageAspectRatio: type: string description: Specifies how to display all carousel images. Valid values are horizontal (default) and square. Only supported in Facebook Messenger, Web Messenger, Android SDK and iOS SDK carousels. enum: - horizontal - square required: - type - items fileMessage: type: object properties: type: type: string description: The type of message. default: file mediaUrl: type: string format: uri description: | The URL for media, such as an image, attached to the message. mediaSize: type: number description: The size of the media. readOnly: true mediaType: type: string description: The media type of the file. readOnly: true altText: type: string maxLength: 128 description: An optional description of the file for accessibility purposes. The field will be saved by default with the file name as the value. text: type: string description: The text content of the message. blockChatInput: type: boolean description: When set to true, the chat input will be disabled on supported client implementations when the message is the most recent one in the history. Can be used for guided flows or to temporarily disable the user's ability to send messages in the conversation. htmlText: $ref: '#/components/schemas/htmlText' markdownText: $ref: '#/components/schemas/markdownText' attachmentId: type: string description: An identifier used by Sunshine Conversations for internal purposes. required: - type - mediaUrl field: properties: type: type: string description: The field type. enum: - email - select - text name: type: string description: The name of the field. Must be unique per form or formResponse. minLength: 1 maxLength: 128 label: type: string description: The label of the field. What the field is displayed as on Web Messenger. minLength: 1 maxLength: 128 text: type: string description: Specifies the response for a text field. minLength: 1 maxLength: 256 email: type: string description: Specifies the response for a email field. minLength: 1 maxLength: 128 select: type: array description: Array of objects representing the response for a field of type select. Form and formResponse messages only. items: type: object format: type: string enum: - integer - decimal description: Specifies the format for a text field. required: - type - name - label formOptions: type: array description: Array of objects representing options for a field of type select. items: type: object properties: label: type: string description: The label of the option. What the option is displayed as on Web Messenger. minLength: 1 maxLength: 128 name: type: string description: The name of the field. Must be unique per field. minLength: 1 maxLength: 128 maxItems: 200 formMessageField: allOf: - $ref: '#/components/schemas/field' - type: object description: | Properties that can be expected to receive inside a form message field. properties: placeholder: type: string description: Placeholder text for the field. Form message only. minLength: 1 maxLength: 128 minSize: type: integer description: The minimum allowed length for the response for a field of type text. Form message only. default: 1 minimum: 1 maximum: 256 maxSize: type: integer description: The maximum allowed length for the response for a field of type text. Form message only. default: 128 minimum: 1 maximum: 256 options: $ref: '#/components/schemas/formOptions' formMessage: type: object description: A form type message. properties: type: type: string description: The type of message. default: form submitted: type: boolean description: Flag which states whether the form is submitted. readOnly: true blockChatInput: type: boolean description: When set to true, the chat input will be disabled on supported client implementations when the message is the most recent one in the history. Can be used for guided flows or to temporarily disable the user's ability to send messages in the conversation.. fields: type: array items: $ref: '#/components/schemas/formMessageField' description: An array of objects representing fields associated with the message. Only present in form and formResponse messages. minItems: 1 maxItems: 20 text: type: string description: An optional text to display above form links on social channels. required: - type - fields formResponseMessageField: allOf: - $ref: '#/components/schemas/field' - type: object description: | Properties that can be expected to receive inside a form response message field. properties: quotedMessageId: type: string description: The messageId for the form that this response belongs to. writeOnly: true formResponseMessage: type: object description: A formResponse type message is a response to a form type message. formResponse type messages are only supported as responses to form messages on Web Messenger and cannot be sent via the API. properties: type: type: string description: The type of message. default: formResponse fields: type: array description: Array of field objects that contain the submitted fields. items: $ref: '#/components/schemas/formResponseMessageField' minItems: 1 maxItems: 20 textFallback: type: string description: 'A string containing the `label: value` of all fields, each separated by a newline character.' readOnly: true required: - type - fields imageMessage: type: object properties: type: type: string description: The type of message. default: image mediaUrl: type: string format: uri description: | The URL for media, such as an image, attached to the message. mediaType: type: string description: The type of media. maxLength: 128 readOnly: true mediaSize: type: number description: The size of the media in bytes. readOnly: true altText: type: string maxLength: 128 description: An optional description of the image for accessibility purposes. The field will be saved by default with the file name as the value. text: type: string description: The text content of the message. blockChatInput: type: boolean description: When set to true, the chat input will be disabled on supported client implementations when the message is the most recent one in the history. Can be used for guided flows or to temporarily disable the user's ability to send messages in the conversation. htmlText: $ref: '#/components/schemas/htmlText' markdownText: $ref: '#/components/schemas/markdownText' actions: type: array description: Array of message actions. items: $ref: '#/components/schemas/action' attachmentId: type: string description: An identifier used by Sunshine Conversations for internal purposes. required: - type - mediaUrl listMessage: type: object title: ListMessage description: | List messages are a vertically scrollable set of items that may each contain text, an image, and message actions. Not all messaging channels fully support list messages. * Facebook Messenger and WeChat have native support. * For LINE and our Android, iOS and Web SDK, Sunshine Conversations converts list messages to carousel. * On WhatsApp, Telegram and Twitter, Sunshine Conversations converts list messages to multiple rich messages. * On all other platforms, Sunshine Conversations converts list messages to raw text. properties: type: type: string description: The type of message. default: list blockChatInput: type: boolean description: When set to true, the chat input will be disabled on supported client implementations when the message is the most recent one in the history. Can be used for guided flows or to temporarily disable the user's ability to send messages in the conversation. items: type: array description: An array of objects representing the items associated with the message. Only present in carousel and list type messages. items: $ref: '#/components/schemas/item' minItems: 1 maxItems: 10 actions: type: array description: An array of objects representing the actions associated with the message. The array length is limited by the third party channel. items: $ref: '#/components/schemas/actionSubset' minItems: 1 maxItems: 10 required: - type - items locationMessage: type: object description: A location type message includes the coordinates (latitude and longitude) of a location and an optional location object which can include the name and address of the location. Typically sent in response to a Location Request. properties: type: type: string description: The type of message. default: location text: type: string description: The fallback text message used when location messages are not supported by the channel. readOnly: true blockChatInput: type: boolean description: When set to true, the chat input will be disabled on supported client implementations when the message is the most recent one in the history. Can be used for guided flows or to temporarily disable the user's ability to send messages in the conversation. coordinates: type: object description: The coordinates of the location. properties: lat: type: number description: Global latitude. long: type: number description: Global longitude. required: - lat - long location: type: object description: Information about the location. properties: address: type: string description: A string representing the address of the location. name: type: string description: A string representing the name of the location. required: - type - coordinates templateMessage: type: object properties: type: type: string description: The type of message. default: template blockChatInput: type: boolean description: When set to true, the chat input will be disabled on supported client implementations when the message is the most recent one in the history. Can be used for guided flows or to temporarily disable the user's ability to send messages in the conversation. template: type: object description: The whatsapp template message to send. For more information, consult the [guide](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/message-overrides/#template-messages). `schema` must be set to `whatsapp`. required: - type - template content: oneOf: - $ref: '#/components/schemas/textMessage' - $ref: '#/components/schemas/carouselMessage' - $ref: '#/components/schemas/fileMessage' - $ref: '#/components/schemas/formMessage' - $ref: '#/components/schemas/formResponseMessage' - $ref: '#/components/schemas/imageMessage' - $ref: '#/components/schemas/listMessage' - $ref: '#/components/schemas/locationMessage' - $ref: '#/components/schemas/templateMessage' discriminator: propertyName: type mapping: text: '#/components/schemas/textMessage' carousel: '#/components/schemas/carouselMessage' file: '#/components/schemas/fileMessage' form: '#/components/schemas/formMessage' formResponse: '#/components/schemas/formResponseMessage' image: '#/components/schemas/imageMessage' list: '#/components/schemas/listMessage' location: '#/components/schemas/locationMessage' template: '#/components/schemas/templateMessage' client: type: object x-resourceId: Clients properties: id: type: string description: The unique ID of the client. example: 5c9a34160c89726709136733 type: $ref: '#/components/schemas/clientType' status: type: string description: The client status. Indicates if the client is able to receive messages or not. Can be pending, inactive, active, or blocked. enum: - active - blocked - inactive - pending example: active integrationId: type: string description: The ID of the integration that the client was created for. Unused for clients of type sdk, as they incorporate multiple integrations. nullable: true example: 582dedf230e788746891281a externalId: type: string description: The ID of the user on an external channel. For example, the user’s phone number for Twilio, or their page-scoped user ID for Facebook Messenger. Applies only to non-SDK clients. nullable: true example: your-own-id lastSeen: type: string description: A datetime string with the format `YYYY-MM-DDThh:mm:ss.SSSZ` representing the last time the user interacted with this client. nullable: true example: '2020-08-20T16:13:07.462Z' linkedAt: type: string description: A timestamp signifying when the client was added to the user. Formatted as `YYYY-MM-DDThh:mm:ss.SSSZ`. nullable: true example: '2020-06-23T14:33:47.492Z' displayName: type: string description: The user's display name on the channel. nullable: true example: Steve avatarUrl: type: string description: The URL for the user's avatar on the channel. format: uri nullable: true info: type: object description: A flat curated object with properties that vary for each client platform. All keys are optional and not guaranteed to be available. nullable: true raw: type: object description: An object with raw properties that vary for each client platform. All keys are optional and not guaranteed to be available. nullable: true device: type: object x-resourceId: Devices properties: id: type: string description: The unique ID of the device. example: de13bee15b51033b34162411 type: type: string description: The type of integration that the device represents. enum: - android - ios - web guid: type: string description: A unique identifier for the device, generated client-side by the SDK. clientId: type: string description: The id of the client to which this device is associated. status: type: string description: The device status. Indicates if the device will receive push notifications or not. enum: - active - inactive integrationId: type: string description: The ID of the integration that the device was created for. lastSeen: type: string description: A datetime string with the format YYYY-MM-DDThh:mm:ss.SSSZ representing the last time the user interacted with this device. pushNotificationToken: type: string description: The token used for push notifications on Android and iOS devices. nullable: true info: type: object description: A flat curated object with properties that vary for each SDK platform. All keys are optional and not guaranteed to be available. nullable: true additionalProperties: true appVersion: type: string description: Version of the mobile app in which the SDK is embedded. Not applicable for devices of type web. nullable: true source: type: object description: The source of the message. properties: type: type: string description: An identifier for the channel from which a message originated. May include one of api, sdk, messenger, or any number of other channels. example: ios integrationId: type: string description: Identifier indicating which integration the message was sent from. For user messages only. example: de13bee15b51033b34162411 nullable: true originalMessageId: type: string description: Message identifier assigned by the originating channel. example: 5f40256af057d0000dda9bd7 nullable: true originalMessageTimestamp: type: string description: A datetime string with the format `YYYY-MM-DDThh:mm:ss.SSSZ` representing when the third party channel received the message. example: '2019-03-21T18:45:53.720Z' nullable: true client: allOf: - $ref: '#/components/schemas/client' description: The client from which the user authored the message or activity, if applicable. This field is not applicable in API responses, it is used only in webhook payloads if the `includeFullSource` option is enabled. nullable: true device: allOf: - $ref: '#/components/schemas/device' description: The device from which the user authored the message or activity, if applicable. This field is not applicable in API responses, it is used only in webhook payloads if the `includeFullSource` option is enabled. nullable: true required: - type message: type: object x-resourceId: Messages properties: id: type: string description: The unique ID of the message. example: 5e552ef595e5206375bb835d received: type: string description: A datetime string with the format `YYYY-MM-DDThh:mm:ss.SSSZ` representing when Sunshine Conversations received the message. example: '2019-03-21T18:48:52.760Z' author: $ref: '#/components/schemas/author' activity: allOf: - $ref: '#/components/schemas/activityMessage' description: Details of the system activity that generated this message. This field is used when actions taken by the system generate a persisted message to notify the user or agent of an event that occurred. For example, when a user's Ticket gets closed. This property applies only to informational text messages generated via system events. content: allOf: - $ref: '#/components/schemas/content' description: The content of the message. source: $ref: '#/components/schemas/source' quotedMessage: allOf: - $ref: '#/components/schemas/quotedMessage' description: The quoted message is currently only available for WhatsApp and Web Messenger `formResponse` messages. nullable: true metadata: allOf: - $ref: '#/components/schemas/metadata' nullable: true deleted: type: boolean description: true if the message serves as a placeholder for one that has been deleted. nullable: true references: type: array description: Array of references to external content that were included with this message. items: $ref: '#/components/schemas/reference' minItems: 1 maxItems: 20 nullable: true quotedMessageMessage: title: QuotedMessageMessage type: object required: - type properties: type: type: string description: The type of quotedMessage - a complete Sunshine Conversations message is provided. default: message message: allOf: - $ref: '#/components/schemas/message' quotedMessageExternalMessageId: title: QuotedMessageExternalMessageId type: object required: - type properties: type: type: string description: The type of quotedMessage - `externalMessageId` if no Sunshine Conversations message matched the quoted message. default: externalMessageId externalMessageId: type: string description: The external message Id of the quoted message. quotedMessage: oneOf: - $ref: '#/components/schemas/quotedMessageMessage' - $ref: '#/components/schemas/quotedMessageExternalMessageId' discriminator: propertyName: type mapping: message: '#/components/schemas/quotedMessageMessage' externalMessageId: '#/components/schemas/quotedMessageExternalMessageId' reference: type: object x-resourceId: MessageReferences description: List of references that can be used to link to the sources of a bot answer. properties: uri: type: string format: uri maxLength: 2048 description: The URI of the referenced content. example: https://example.com/article/123 title: type: string minLength: 1 maxLength: 128 description: Optional title for the reference. example: How to integrate messaging APIs description: type: string minLength: 1 maxLength: 256 description: Optional description of the referenced content. example: A comprehensive guide to messaging API integration iconUrl: type: string format: uri pattern: ^https:// maxLength: 2048 description: Optional icon URL for the reference source. If provided explicitly, this value takes precedence. When not provided, auto-populated for recognized sources (Box, Google Drive, Notion, Confluence, Slack, Teams, SharePoint, Seismic, Guru, Coda). example: https://example.com/favicon.png positions: type: array items: type: integer minimum: 0 minItems: 1 maxItems: 20 description: Character offsets in the input text field where this reference's citation marker should be inserted. Positions must be relative to the text field provided in the request (text, markdownText, or htmlText). When positions are present, only one text field may be provided. Positions must not exceed the length of the input text. The system recomputes positions relative to the final htmlText for internal processing. example: - 42 - 128 source: type: string minLength: 1 maxLength: 128 description: Provider or brand name (e.g., "Confluence", "Slack", "Google Drive"). Displayed as-is without translation. Required when sourceType is present. example: Confluence sourceType: type: string minLength: 1 maxLength: 128 description: Type of the source resource. Must be one of the recognized values - File, Folder, Page, Database, Blog, Content, Collection, Card, Document, Row, Message. Determines the card layout for rendering. Requires source to be present. example: Page required: - uri dependencies: sourceType: - source messageListResponse: type: object title: MessageListResponse properties: messages: type: array description: List of returned messages. items: $ref: '#/components/schemas/message' meta: $ref: '#/components/schemas/meta' links: $ref: '#/components/schemas/links' destination: oneOf: - type: object title: integrationId properties: integrationId: type: string description: | The id of the integration to deliver the message to. Will return an error if the integration does not exist or if the user does not have a client for the integration attached to the conversation. example: 582dedf230e788746891281a - type: object title: integrationType properties: integrationType: type: string description: | The type of the integration to deliver the message to. Can be set to `none` if sending a [silent message](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/sending-messages/#silent-messages). Will return an error if the user does not have a client of that type attached to the conversation. example: whatsapp description: | 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`. appleMessageOverridePayload: type: object description: The exact payload to send to the channel. properties: payload: type: object withCapabilities: type: array items: type: string enum: - LIST - TIME - FORM - QUICK - AUTH2 description: | List of capabilities needed for the override message to be received by the end user. `LIST` : for list picker; `TIME` : for time picker; `FORM` : for form; `QUICK` : for quick reply; `AUTH2` : for authentication example: - LIST messageOverridePayload: type: object description: The exact payload to send to the channel. properties: payload: type: object messageOverride: anyOf: - type: object title: MessageOverrideApple properties: apple: $ref: '#/components/schemas/appleMessageOverridePayload' - type: object title: MessageOverrideLine properties: line: $ref: '#/components/schemas/messageOverridePayload' - type: object title: MessageOverrideMessenger properties: messenger: $ref: '#/components/schemas/messageOverridePayload' - type: object title: MessageOverrideWhatsapp properties: whatsapp: $ref: '#/components/schemas/messageOverridePayload' description: 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. messagePost: type: object properties: author: allOf: - $ref: '#/components/schemas/author' description: The author of the message. content: allOf: - $ref: '#/components/schemas/content' description: The content of the message. destination: $ref: '#/components/schemas/destination' metadata: $ref: '#/components/schemas/metadata' override: $ref: '#/components/schemas/messageOverride' schema: type: string description: | 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). example: whatsapp required: - author - content messagePostResponse: type: object description: The created messages. A single request may produce multiple messages when the shorthand syntax is used to send a template message with leading text. properties: messages: type: array items: $ref: '#/components/schemas/message' activityTypes: type: object properties: type: type: string description: If the author type is `user`, only `conversation:read` is supported. enum: - conversation:read - typing:start - typing:stop activityPost: allOf: - type: object properties: author: allOf: - $ref: '#/components/schemas/author' description: The author of the activity. - $ref: '#/components/schemas/activityTypes' required: - author - type passControlBody: type: object properties: switchboardIntegration: type: string description: | The switchboard integration that will become active. May be referenced by its `id`, `name`, or `integrationType`, in that order of precedence. In case of ambiguity (for example, if the `custom` type is specified, but more than one are present in the switchboard), an error will be raised. The `next` keyword may also be used to transfer control to the next switchboard integration designated in the switchboard configuration, without having to know what it is. example: next metadata: allOf: - $ref: '#/components/schemas/metadata' description: 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. required: - switchboardIntegration releaseControlBody: type: object properties: metadata: allOf: - $ref: '#/components/schemas/metadata' description: 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. offerControlBody: type: object properties: switchboardIntegration: type: string description: | The switchboard integration that will become pending. May be referenced by its `id`, `name`, or `integrationType`, in that order of precedence. In case of ambiguity (for example, if the `custom` type is specified, but more than one are present in the switchboard), an error will be raised. The `next` keyword may also be used to offer control to the next switchboard integration designated in the switchboard configuration, without having to know what it is. This cannot match the active switchboard integration. example: next metadata: allOf: - $ref: '#/components/schemas/metadata' description: 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. required: - switchboardIntegration acceptControlBody: type: object properties: metadata: allOf: - $ref: '#/components/schemas/metadata' description: 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. downloadMessageRefBody: allOf: - type: object properties: userId: type: string description: The id of the user. example: 5963c0d619a30a2e00de36b8 apple: type: object description: The message ref returned by Apple. required: - interactiveDataRef properties: interactiveDataRef: type: object description: interactiveDataRef can be found in the passthrough webhook. required: - url - bid - key - signature - owner properties: url: type: string bid: type: string key: type: string signature: type: string owner: type: string required: - userId metaConversionEvent: type: object description: The conversion event data expected by Meta. required: - payload properties: payload: type: object description: The payload to be sent to Meta's conversion events API. Should contain the exact structure expected by [Meta's Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event) except for the `user_data` and `messaging_channel` fields, which will be provided by Zendesk. required: - data properties: data: type: array description: The array of conversion events to be sent to Meta's conversion events API. items: type: object conversionEventsBody: oneOf: - type: object title: MessengerConversionEventsBody properties: messenger: $ref: '#/components/schemas/metaConversionEvent' - type: object title: InstagramConversionEventsBody properties: instagram: $ref: '#/components/schemas/metaConversionEvent' - type: object title: WhatsAppConversionEventsBody properties: whatsapp: $ref: '#/components/schemas/metaConversionEvent' conversionEvents: type: object description: Details about the conversion events that were processed. properties: datasetId: type: string description: The ID of the dataset that the conversion events were sent to. eventsReceived: type: integer description: The number of conversion events that were received and processed. conversionEventsResponse: type: object title: ConversionEventsResponse properties: conversionEvents: $ref: '#/components/schemas/conversionEvents' integration: type: object x-resourceId: Integrations description: The integration. properties: id: type: string description: The unique ID of the integration. readOnly: true example: 5e4af71a81966cfff3ef6550 type: type: string example: android status: $ref: '#/components/schemas/status' displayName: type: string description: A human-friendly name used to identify the integration. example: Channel name maxLength: 100 nullable: true required: - type discriminator: propertyName: type mapping: android: '#/components/schemas/android' apple: '#/components/schemas/apple' custom: '#/components/schemas/custom' instagram: '#/components/schemas/instagram' ios: '#/components/schemas/ios' line: '#/components/schemas/line' mailgun: '#/components/schemas/mailgun' messagebird: '#/components/schemas/messagebird' messenger: '#/components/schemas/messenger' telegram: '#/components/schemas/telegram' twilio: '#/components/schemas/twilio' twitter: '#/components/schemas/twitter' unity: '#/components/schemas/unity' viber: '#/components/schemas/viber' web: '#/components/schemas/web' whatsapp: '#/components/schemas/whatsapp' defaultResponderId: type: object title: Default Responder ID properties: defaultResponderId: type: string description: | The default responder ID for the integration. This is the ID of the responder that will be used to send messages to the user. For more information, refer to the Switchboard guide. nullable: true writeOnly: true defaultResponder: type: object title: Default Responder properties: defaultResponder: type: object description: | The default responder for the integration. This is the responder that will be used to send messages to the user. For more information, refer to the Switchboard guide. nullable: true readOnly: true properties: name: type: string description: The name of the switchboard integration. integrationId: type: string description: The unique ID of the integration. example: 5e4af71a81966cfff3ef6550 integrationType: type: string description: The type of the integration. deliverStandbyEvents: type: boolean description: Indicates whether the switchboard should deliver standby events. nextSwitchboardIntegrationId: type: string description: The unique ID of the next switchboard integration. nullable: true messageHistoryCount: type: number description: The number of messages to keep in the message history. inherited: type: boolean description: Indicates whether the default responder is inherited from the switchboard's global config or not. Returns `false` if a per-channel responder override has been set for this integration, and `true` otherwise. showAIDisclaimer: type: object title: show AI disclaimer properties: showAIDisclaimer: type: boolean default: true description: | When true or not present on the integration, a disclaimer is shown to end users when messages are generated by an AI responder. android: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: |

Note: Firebase Cloud Messaging has deprecated its legacy APIs for HTTP and XMPP. Legacy credentials serverKey and senderId will stop working as of June 2024 and must be replaced with OAuth 2.0 access token based credentials.

To configure an android integration, first visit the [Firebase Console](https://console.firebase.google.com/). Generate a private key from the Service accounts tab in the settings. Copy the `project_id`, `client_email` and `private_key` from the generated JSON file and call the create integrations endpoint with this data. default: android projectId: type: string description: Your project ID from your generated private key file. minLength: 1 writeOnly: true nullable: true example: clientEmail: type: string description: Your client email from your generated private key file. minLength: 1 writeOnly: true nullable: true example: privateKey: type: string description: Your private key from your generated private key file. minLength: 1 writeOnly: true nullable: true example: serverKey: type: string description: Your server key from the fcm console. minLength: 1 writeOnly: true nullable: true example: deprecated: true senderId: type: string description: Your sender id from the fcm console. minLength: 1 nullable: true example: deprecated: true canUserSeeConversationList: type: boolean description: | Allows users to view their list of conversations. By default, the list of conversations will be visible. *This setting only applies to apps where `settings.multiConvoEnabled` is set to `true`*. example: false canUserCreateMoreConversations: type: boolean description: Allows users to create more than one conversation on the android integration. attachmentsEnabled: type: boolean description: | Allows users to send attachments. By default, the setting is set to true. This setting can only be configured in Zendesk Admin Center. readOnly: true - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' apple: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure an Apple Messages for Business integration, acquire the required information and call the Create Integration endpoint. default: apple businessId: type: string description: Apple Messages for Business ID. example: 2740f141-89c1-515f-07eb-1128dd73491 apiSecret: type: string description: Your Apple API secret which is tied to your Messaging Service Provider. writeOnly: true example: QLA//Z13paUYo/2tLReQa-43c5JEAASujGamiY/QTvs= mspId: type: string description: Your Messaging Service Provider ID. example: e7e495d5-bf78-531d-baf6-7f419f7fb592 authenticationMessageSecret: type: string description: A secret used to create the state value when sending Apple authentication 2.0 messages minLength: 88 example: eH3Ea4329FzUGEsWkjQr1dbD1JDpn5Ygo/kbW0/f8gOQ4eHTr31bjDUcCfv3s9QaAwRgpd4sckdlSXwMOAGHBQ== required: - businessId - apiSecret - mspId - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' target: type: string description: URL to be called when the webhook is triggered. example: https://example.com/callback triggers: type: array items: type: string example: - conversation:read - conversation:message description: 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: type: boolean description: A boolean specifying whether webhook payloads should include the complete user schema for events involving a specific user. default: false includeFullSource: type: boolean description: A boolean specifying whether webhook payloads should include the client and device object (when applicable). default: false webhook: type: object x-resourceId: Webhooks properties: id: type: string description: A unique identifier for the webhook. readOnly: true example: 5e554d2cac66fb73a3c01871 version: type: string description: Schema version of the payload delivered to this webhook. Can be `v1`, `v1.1` or `v2`. readOnly: true example: v2 target: $ref: '#/components/schemas/target' triggers: $ref: '#/components/schemas/triggers' secret: type: string description: Webhook secret, used to verify the origin of incoming requests. example: 8564b3e6a8b20a4bdb68b05ce9bc5936 includeFullUser: $ref: '#/components/schemas/includeFullUser' includeFullSource: $ref: '#/components/schemas/includeFullSource' required: - target - triggers custom: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a custom integration you need to setup a webhook with a set of triggers and target. default: custom webhooks: type: array items: $ref: '#/components/schemas/webhook' description: An array of webhooks associated with the custom integration. minItems: 1 maxItems: 1 required: - webhooks instagram: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | Instagram Direct setup steps: - Take note of your Facebook app ID and secret (apps can be created at [developer.facebook.com](https://developer.facebook.com)); - The Facebook app must have been submitted to Meta for app review with the "pages_manage_metadata" (to retrieve Page Access Tokens for the Pages and apps that the app user administers and to set a webhook), "instagram_basic", and "instagram_manage_messages" (to retrieve basic Instagram account information and send messages) permissions. - In order to integrate an Instagram Direct app, you must acquire a Page Access Token from your user. Once you have acquired a page access token from your user, call the Create Integration endpoint with your app secret and ID and the user’s page access token. default: instagram pageAccessToken: type: string description: The Facebook Page Access Token of the Facebook page that is linked to your Instagram account. writeOnly: true nullable: true example: your_page_access_token appId: type: string description: Your Facebook App ID. example: your_facebook_app_id appSecret: type: string description: Your Facebook App secret. writeOnly: true nullable: true example: your_facebook_app_secret businessName: type: string description: Your Instagram Business account name readOnly: true example: instagram_name businessUsername: type: string description: Your Instagram Business unique username readOnly: true example: instagram_username pageId: type: string description: The ID of the Facebook Page linked to your Instagram Business account readOnly: true example: '106731941223392' businessId: type: string description: The ID of the Instagram Business account readOnly: true example: '17841444303043201' username: type: string description: The Facebook user's username. This is returned when integrating through the Dashboard readOnly: true example: facebook_username userId: type: string description: The Facebook user's user ID. This is returned when integrating through the Dashboard readOnly: true example: '100885965124932' storyRepliesEnabled: type: boolean description: | When true, a message is generated when a user replies to your business story with text or a reaction. default: true storyMentionsEnabled: type: boolean description: | When true, a referral event is generated when a user mentions your business in their own story. default: true required: - pageAccessToken - appId - appSecret - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' ios: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure an ios integration, call the create integration endpoint with a base64 encoded Apple Push Notification certificate from the [Apple Developer Portal](https://developer.apple.com/). default: ios certificate: type: string description: | The binary of your APN certificate base64 encoded. To base64 encode your certificate you can use this command in the terminal: `openssl base64 -in YOUR_CERTIFICATE.p12 | tr -d '\n'` minLength: 1 writeOnly: true nullable: true example: your_APN_certificate password: type: string description: The password for your APN certificate. writeOnly: true example: your_APN_password production: type: boolean description: The APN environment to connect to (Production, if true, or Sandbox). Defaults to value inferred from certificate if not specified. autoUpdateBadge: type: boolean description: Use the unread count of the conversation as the application badge. canUserSeeConversationList: type: boolean description: | Allows users to view their list of conversations. By default, the list of conversations will be visible. *This setting only applies to apps where `settings.multiConvoEnabled` is set to `true`*. example: false canUserCreateMoreConversations: type: boolean description: Allows users to create more than one conversation on the iOS integration. attachmentsEnabled: type: boolean description: | Allows users to send attachments. By default, the setting is set to true. This setting can only be configured in Zendesk Admin Center. readOnly: true - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' line: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | For LINE, each of your customers will need to manually configure a webhook in their LINE configuration page that will point to Sunshine Conversations servers. You must instruct your customers how to configure this manually on their LINE bot page. Once you’ve acquired all the required information, call the Create Integration endpoint. Then, using the returned integration _id, your customer must set the Callback URL field in their LINE Business Center page. The URL should look like the following: `https://app.smooch.io:443/api/line/webhooks/{appId}/{integrationId}`. default: line channelId: type: string description: LINE Channel ID. Can be omitted along with `channelSecret` to integrate LINE to setup a webhook before receiving the `channelId` and `channelSecret` back from LINE. example: '1286564967' channelSecret: type: string description: LINE Channel Secret. Can be omitted along with `channelId` to integrate LINE to setup a webhook before receiving the `channelId` and `channelSecret` back from LINE. example: your_line_channel_secret channelAccessToken: type: string description: LINE Channel Access Token. example: your_line_channel_token serviceCode: type: string description: LINE Service Code. example: your_line_service_code switcherSecret: type: string description: LINE Switcher Secret. minLength: 1 example: your_line_switcher_secret qrCodeUrl: type: string description: URL provided by LINE in the [Developer Console](https://developers.line.biz/console/). example: https://qr-official.line.me/M/1O4fb8.png lineId: type: string description: LINE Basic ID. Is automatically set when qrCodeUrl is updated. readOnly: true example: 104fb8 - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' mailgun: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a Mailgun integration, visit the API Keys tab in the settings page of the Mailgun dashboard and copy your active API key. Call the Create Integration endpoint with your API Key, a domain you have configured in Mailgun, and the incoming address you would like to use. Must have the same domain as the one specified in the domain parameter. default: mailgun apiKey: type: string description: The public API key of your Mailgun account. minLength: 1 writeOnly: true nullable: true example: key-f265hj32f0sd897lqd2j5keb96784043 signingKey: type: string description: The webhook signing key of your Mailgun account. If not specified, the `apiKey` will be used for webhook signature validation instead. You must include this if your Mailgun signing key and API key have different values. minLength: 1 example: 12d99f5a15355c180971bed7494d578b093c958f57766f3fe750761baed12345 domain: type: string description: The domain used to relay email. This domain must be configured and verified in your Mailgun account. minLength: 1 example: sandbox123.mailgun.org incomingAddress: type: string description: Sunshine Conversations will receive all emails sent to this address. It will also be used as the Reply-To address. minLength: 1 example: mytestemail@sandbox123.mailgun.org hideUnsubscribeLink: type: boolean description: A boolean value indicating whether the unsubscribe link should be omitted from outgoing emails. When enabled, it is expected that the business is providing the user a way to unsubscribe by some other means. By default, the unsubscribe link will be included in all outgoing emails. fromAddress: type: string description: Email address to use as the From and Reply-To address if it must be different from incomingAddress. Only use this option if the address that you supply is configured to forward emails to the incomingAddress, otherwise user replies will be lost. You must also make sure that the domain is properly configured as a mail provider so as to not be flagged as spam by the user’s email client. May be unset with null. minLength: 1 nullable: true example: test@sandbox123.mailgun.org required: - apiKey - domain - incomingAddress - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' messagebird: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a MessageBird integration, acquire the accessKey, the signingKey and the MessageBird number you would like to use, then call the Create Integration endpoint. The response will include the integration’s `_id` and `webhookSecret`, which must be used to configure the webhook in MessageBird. In the Flow Builder for the MessageBird number you’ve used to integrate, add a new step with the following settings: - Create a new Call HTTP endpoint with SMS flow. - Select your desired SMS number for Incoming SMS. - Click on Forward to URL and set its method to POST. - Then, using the integration _id and webhookSecret returned from the create integration call, enter the following into the URL field: `https://app.smooch.io/api/messagebird/webhooks/{appId}/{integrationId}/{webhookSecret}` - Select application/json for the Set Content-Type header field. - Save and publish your changes. default: messagebird accessKey: type: string description: The public API key of your MessageBird account. minLength: 1 writeOnly: true nullable: true example: 9V2iJmd93kFJ390L9495JCl11 signingKey: type: string description: The signing key of your MessageBird account. Used to validate the webhooks' origin. minLength: 1 writeOnly: true nullable: true example: Uu6N09Lkdji3820DJIO89I39sl9dJ originator: type: string description: Sunshine Conversations will receive all messages sent to this phone number. minLength: 1 example: '12262121021' webhookSecret: type: string description: The secret that is used to configure webhooks in MessageBird. readOnly: true example: 72ade38394d1da51566cede33bd1e67e required: - accessKey - signingKey - originator - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' messenger: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | Facebook Messenger Setup steps: - Take note of your Facebook app ID and secret (apps can be created at developer.facebook.com); - The Facebook app must have been submitted to Meta for app review with the “pages_manage_metadata” (to retrieve Page Access Tokens for the Pages, apps that the app user administers and set a webhook) and “pages_messaging” (to send messages) permissions. - In order to integrate a Facebook Messenger app you must acquire a Page Access Token from your user. Once you have acquired a page access token from your user, call the Create Integration endpoint with your app secret and ID and the user’s page access token. default: messenger pageAccessToken: type: string description: A Facebook Page Access Token. nullable: true example: your_access_token appId: type: string description: A Facebook App ID. example: your_facebook_app_id appSecret: type: string description: A Facebook App Secret. writeOnly: true nullable: true example: your_facebook_app_secret pageId: type: number description: A Facebook page ID. example: '123212323432123' pageName: type: string description: A Facebook page name. example: An Awesome Page required: - pageAccessToken - appId - appSecret - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' telegram: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a Telegram integration, acquire the required information from the user and call the Create Integration endpoint. default: telegram token: type: string description: Telegram Bot Token. minLength: 1 writeOnly: true nullable: true example: 192033615:AAEuee2FS2JYKWfDlTulfygjaIGJi4s username: type: string description: Username of the botId readOnly: true botId: type: string description: A human-friendly name used to identify the integration. readOnly: true required: - token - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' twilio: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a Twilio integration, acquire the required information from the user and call the Create Integration endpoint. default: twilio accountSid: type: string description: Twilio Account SID. example: ACa1b4c65ee0722712fab89867cb14eac7 authToken: type: string description: Twilio Auth Token. minLength: 1 writeOnly: true nullable: true example: 160c024303f53049e1e060fd67ca6aefc phoneNumberSid: type: string description: SID for specific phone number. One of `messagingServiceSid` or `phoneNumberSid` must be provided when creating a Twilio integration. minLength: 1 example: PN0674df0ecee0c9819bca0ff0bc0a159e messagingServiceSid: type: string description: SID for specific messaging service. One of `messagingServiceSid` or `phoneNumberSid` must be provided when creating a Twilio integration. minLength: 1 required: - accountSid - authToken - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' twitter: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To set up a Twitter integration, please follow the steps outlined in the [Twitter Setup Guide](https://docs.smooch.io/guide/twitter/#setup). default: twitter tier: type: string description: Your Twitter app's tier. Only "enterprise" is supported for new integrations. enum: - enterprise envName: type: string description: The Twitter dev environments label. Only required / used for sandbox and premium tiers. minLength: 1 readOnly: true consumerKey: type: string description: The consumer key for your Twitter app. minLength: 1 writeOnly: true example: your_consumer_key consumerSecret: type: string description: The consumer key secret for your Twitter app. minLength: 1 writeOnly: true nullable: true example: your_consumer_secret accessTokenKey: type: string description: The access token key obtained from your user via oauth. minLength: 1 writeOnly: true example: your_access_token_key accessTokenSecret: type: string description: The access token secret obtained from your user via oauth. minLength: 1 writeOnly: true nullable: true example: your_access_token_secret required: - tier - consumerKey - consumerSecret - accessTokenKey - accessTokenSecret - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' unity: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a Unity integration, create an integration with type 'unity' by calling the Create Integration endpoint. default: unity canUserSeeConversationList: type: boolean description: | Allows users to view their list of conversations. By default, the list of conversations will be visible. *This setting only applies to apps where `settings.multiConvoEnabled` is set to `true`*. example: false canUserCreateMoreConversations: type: boolean description: Allows users to create more than one conversation on the Unity integration. attachmentsEnabled: type: boolean description: | Allows users to send attachments. By default, the setting is set to true. This setting can only be configured in Zendesk Admin Center. readOnly: true - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' viber: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a Viber integration, acquire the Viber Public Account token from the user and call the Create Integration endpoint. default: viber token: type: string description: Viber Public Account token. minLength: 1 writeOnly: true nullable: true example: 445da6az1s345z78-dazcczb2542zv51a-e0vc5fva17480im9 uri: type: string description: Unique URI of the Viber account. readOnly: true accountId: type: string description: Unique ID of the Viber account. readOnly: true required: - token - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' prechatCapture: type: object properties: avatarUrl: type: string description: Sets the URL of the avatar to use for the automatic reply to the prechat capture messages. default: undefined example: https://domain.com/images/avatar.png enabled: type: boolean description: If true, enables the Prechat Capture add-on when the Web Messenger is initialized. default: false enableEmailLinking: type: boolean description: f true and Mailgun is integrated, will automatically link submitted emails. default: false fields: type: array items: $ref: '#/components/schemas/field' description: Array of Fields. Overrides the default Prechat Capture fields to define a custom form. example: - type: email name: email label: Email placeholder: your@email.com - type: text name: company-website label: Company website placeholder: mycompany.com web: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a Web Messenger integration, acquire the required information and call the Create Integration endpoint. default: web brandColor: type: string description: | This color will be used in the messenger header and the button or tab in idle state. Must be a 3 or 6-character hexadecimal color. default: 65758e fixedIntroPane: type: boolean description: | When true, the introduction pane will be pinned at the top of the conversation instead of scrolling with it. default: false conversationColor: type: string description: | This color will be used for customer messages, quick replies and actions in the footer. Must be a 3 or 6-character hexadecimal color. default: 0099ff actionColor: type: string description: | This color will be used for call-to-actions inside your messages. Must be a 3 or 6-character hexadecimal color. default: 0099ff displayStyle: type: string description: | Choose how the messenger will appear on your website. Must be either button or tab. default: button buttonIconUrl: type: string description: | With the button style Web Messenger, you have the option of selecting your own button icon. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format. nullable: true example: https://domain.com/images/avatar.png buttonWidth: type: string description: | With the button style Web Messenger, you have the option of specifying the button width. default: '58' buttonHeight: type: string description: | With the button style Web Messenger, you have the option of specifying the button height. default: '58' integrationOrder: type: array description: | Array of integration IDs, order will be reflected in the Web Messenger. When set, only integrations from this list will be displayed in the Web Messenger. If unset, all integrations will be displayed. items: type: string nullable: true example: '["59fc8466260f48003505228b", "59d79780481d34002b7d3617"]' businessName: type: string description: A custom business name for the Web Messenger. example: Kent Shop businessIconUrl: type: string description: | A custom business icon url for the Web Messenger. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format. example: https://www.gravatar.com/image.jpg backgroundImageUrl: type: string description: | A background image url for the conversation. Image will be tiled to fit the window. example: https://a-beautiful-tile.png originWhitelist: type: array description: | A list of origins to whitelist. When set, only the origins from this list will be able to initialize the Web Messenger. If unset, all origins are whitelisted. The elements in the list should follow the serialized-origin format from RFC 6454: scheme "://" host [ ":" port ], where scheme is http or https. items: type: string nullable: true example: https://yourdomain.com prechatCapture: description: | Object whose properties can be set to specify the add-on’s options. See the [guide](https://docs.smooch.io/guide/web-messenger/#prechat-capture) to learn more about Prechat Capture. allOf: - $ref: '#/components/schemas/prechatCapture' canUserSeeConversationList: type: boolean description: | Allows users to view their list of conversations. By default, the list of conversations will be visible. *This setting only applies to apps where `settings.multiConvoEnabled` is set to `true`*. example: false canUserCreateMoreConversations: type: boolean description: | Allows users to create more than one conversation on the web messenger integration. attachmentsEnabled: type: boolean description: | Allows users to send attachments. By default, the setting is set to true. This setting can only be configured in Zendesk Admin Center. readOnly: true - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' whatsapp: allOf: - $ref: '#/components/schemas/integration' - type: object properties: type: type: string description: | To configure a WhatsApp integration, use your WhatsApp API Client connection information. Sunshine Conversations can provide WhatsApp API Client hosting for approved brands. See our [WhatsApp guide](https://docs.smooch.io/guide/whatsapp/#whatsapp-api-client) for more details on WhatsApp API Client hosting. default: whatsapp hsmFallbackLanguage: type: string description: Specify a fallback language to use when sending WhatsApp message template using the short hand syntax. Defaults to en_US. See WhatsApp documentation for more info. nullable: true default: en_US accountId: type: string description: The business ID associated with the WhatsApp account. In combination with accountManagementAccessToken, it’s used for Message Template Reconstruction. nullable: true example: your_whatsApp_account_id accountManagementAccessToken: type: string description: An access token associated with the accountId used to query the WhatsApp Account Management API. In combination with accountId, it’s used for Message Template Reconstruction. nullable: true example: your_access_token phoneNumber: type: string description: The phone number that is associated with the deployment of this integration, if one exists. readOnly: true nullable: true example: '15144441919' - $ref: '#/components/schemas/defaultResponderId' - $ref: '#/components/schemas/defaultResponder' - $ref: '#/components/schemas/showAIDisclaimer' status: type: string description: The status of the integration. enum: - inactive - active - error readOnly: true integrationListResponse: type: object properties: integrations: type: array description: List of returned integrations. items: $ref: '#/components/schemas/integration' meta: $ref: '#/components/schemas/meta' links: $ref: '#/components/schemas/links' integrationResponse: type: object title: integrationResponse properties: integration: $ref: '#/components/schemas/integration' integrationUpdateBase: type: object properties: displayName: type: string description: A human-friendly name used to identify the integration. `displayName` can be unset by changing it to `null`. minLength: 1 maxLength: 100 nullable: true example: My awesome integration defaultResponderId: type: string description: | The default responder ID for the integration. This is the ID of the responder that will be used to send messages to the user. For more information, refer to the Switchboard guide. nullable: true showAIDisclaimer: type: boolean description: | When true or not present on the integration, a disclaimer is shown to end users when messages are generated by an AI responder. androidUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object properties: projectId: type: string description: Your project ID from your generated private key file. minLength: 1 writeOnly: true nullable: true example: clientEmail: type: string description: Your client email from your generated private key file. minLength: 1 writeOnly: true nullable: true example: privateKey: type: string description: Your private key from your generated private key file. minLength: 1 writeOnly: true nullable: true example: serverKey: type: string description: Your server key from the fcm console. minLength: 1 writeOnly: true nullable: true example: deprecated: true senderId: type: string description: Your sender id from the fcm console. minLength: 1 nullable: true example: deprecated: true canUserSeeConversationList: type: boolean description: | Allows users to view their list of conversations. By default, the list of conversations will be visible. *This setting only applies to apps where `settings.multiConvoEnabled` is set to `true`*. example: false canUserCreateMoreConversations: type: boolean description: Allows users to create more than one conversation on the android integration. appleUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object properties: authenticationMessageSecret: type: string description: A secret used to create the state value when sending Apple authentication 2.0 messages minLength: 88 example: eH3Ea4329FzUGEsWkjQr1dbD1JDpn5Ygo/kbW0/f8gOQ4eHTr31bjDUcCfv3s9QaAwRgpd4sckdlSXwMOAGHBQ== customUpdate: type: object properties: displayName: type: string description: A human-friendly name used to identify the integration. `displayName` can be unset by changing it to `null`. minLength: 1 maxLength: 100 nullable: true example: My awesome integration instagramUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object properties: pageAccessToken: type: string description: A Facebook Page Access Token. example: your_access_token storyRepliesEnabled: type: boolean description: | When true, a message is generated when a user replies to your business story with text or a reaction. storyMentionsEnabled: type: boolean description: | When true, a referral event is generated when a user mentions your business in their own story. iosUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object properties: certificate: type: string description: The binary of your APN certificate base64 encoded. minLength: 1 writeOnly: true nullable: true example: your_APN_certificate password: type: string description: The password for your APN certificate. writeOnly: true example: your_APN_password production: type: boolean description: The APN environment to connect to (Production, if true, or Sandbox). Defaults to value inferred from certificate if not specified. autoUpdateBadge: type: boolean description: Use the unread count of the conversation as the application badge. canUserSeeConversationList: type: boolean description: | Allows users to view their list of conversations. By default, the list of conversations will be visible. *This setting only applies to apps where `settings.multiConvoEnabled` is set to `true`*. example: false canUserCreateMoreConversations: type: boolean description: Allows users to create more than one conversation on the iOS integration. lineUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' mailgunUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object properties: hideUnsubscribeLink: type: boolean description: A boolean value indicating whether the unsubscribe link should be omitted from outgoing emails. When enabled, it is expected that the business is providing the user a way to unsubscribe by some other means. By default, the unsubscribe link will be included in all outgoing emails. fromAddress: type: string description: Email address to use as the From and Reply-To address if it must be different from incomingAddress. Only use this option if the address that you supply is configured to forward emails to the incomingAddress, otherwise user replies will be lost. You must also make sure that the domain is properly configured as a mail provider so as to not be flagged as spam by the user’s email client. May be unset with null. minLength: 1 nullable: true example: test@sandbox123.mailgun.org messageBirdUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' messengerUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object properties: pageAccessToken: type: string description: A Facebook Page Access Token. example: your_access_token telegramUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' twilioUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' twitterUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' unityUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object properties: canUserSeeConversationList: type: boolean description: | Allows users to view their list of conversations. By default, the list of conversations will be visible. *This setting only applies to apps where `settings.multiConvoEnabled` is set to `true`*. example: false canUserCreateMoreConversations: type: boolean description: Allows users to create more than one conversation on the Unity integration. viberUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' webUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object description: | To configure a Web Messenger integration, acquire the required information and call the Create Integration endpoint. properties: brandColor: type: string description: This color will be used in the messenger header and the button or tab in idle state. Must be a 3 or 6-character hexadecimal color. default: 65758e fixedIntroPane: type: boolean description: When true, the introduction pane will be pinned at the top of the conversation instead of scrolling with it. default: false conversationColor: type: string description: This color will be used for customer messages, quick replies and actions in the footer. Must be a 3 or 6-character hexadecimal color. default: 0099ff actionColor: type: string description: This color will be used for call-to-actions inside your messages. Must be a 3 or 6-character hexadecimal color. default: 0099ff displayStyle: type: string description: Choose how the messenger will appear on your website. Must be either button or tab. default: button buttonIconUrl: type: string description: With the button style Web Messenger, you have the option of selecting your own button icon. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format. nullable: true buttonWidth: type: string description: With the button style Web Messenger, you have the option of specifying the button width. default: '58' buttonHeight: type: string description: With the button style Web Messenger, you have the option of specifying the button height. default: '58' integrationOrder: type: array description: Array of integration IDs, order will be reflected in the Web Messenger. When set, only integrations from this list will be displayed in the Web Messenger. If unset, all integrations will be displayed. items: type: string nullable: true example: - 59fc8466260f48003505228b - 59d79780481d34002b7d3617 businessName: type: string description: A custom business name for the Web Messenger. example: Kent Shop businessIconUrl: type: string description: A custom business icon url for the Web Messenger. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format. example: https://www.gravatar.com/image.jpg backgroundImageUrl: type: string description: A background image url for the conversation. Image will be tiled to fit the window. example: https://a-beautiful-tile.png originWhitelist: type: array description: | A list of origins to whitelist. When set, only the origins from this list will be able to initialize the Web Messenger. If unset, all origins are whitelisted. The elements in the list should follow the serialized-origin format from RFC 6454: scheme "://" host [ ":" port ], where scheme is http or https. items: type: string nullable: true prechatCapture: description: Object whose properties can be set to specify the add-on’s options. See the [guide](https://docs.smooch.io/guide/web-messenger/#prechat-capture) to learn more about Prechat Capture. allOf: - $ref: '#/components/schemas/prechatCapture' canUserSeeConversationList: type: boolean description: | Allows users to view their list of conversations. By default, the list of conversations will be visible. *This setting only applies to apps where `settings.multiConvoEnabled` is set to `true`*. example: false canUserCreateMoreConversations: type: boolean description: Allows users to create more than one conversation on the web messenger integration. whatsAppUpdate: allOf: - $ref: '#/components/schemas/integrationUpdateBase' - type: object properties: hsmFallbackLanguage: type: string description: Specify a fallback language to use when sending WhatsApp message template using the short hand syntax. Defaults to en_US. See WhatsApp documentation for more info. nullable: true default: en_US accountId: type: string description: The business ID associated with the WhatsApp account. In combination with accountManagementAccessToken, it’s used for Message Template Reconstruction. nullable: true example: your_whatsApp_account_id accountManagementAccessToken: type: string description: An access token associated with the accountId used to query the WhatsApp Account Management API. In combination with accountId, it’s used for Message Template Reconstruction. nullable: true example: your_access_token integrationUpdate: oneOf: - $ref: '#/components/schemas/androidUpdate' - $ref: '#/components/schemas/appleUpdate' - $ref: '#/components/schemas/customUpdate' - $ref: '#/components/schemas/instagramUpdate' - $ref: '#/components/schemas/iosUpdate' - $ref: '#/components/schemas/lineUpdate' - $ref: '#/components/schemas/mailgunUpdate' - $ref: '#/components/schemas/messageBirdUpdate' - $ref: '#/components/schemas/messengerUpdate' - $ref: '#/components/schemas/telegramUpdate' - $ref: '#/components/schemas/twilioUpdate' - $ref: '#/components/schemas/twitterUpdate' - $ref: '#/components/schemas/unityUpdate' - $ref: '#/components/schemas/viberUpdate' - $ref: '#/components/schemas/webUpdate' - $ref: '#/components/schemas/whatsAppUpdate' apiKey: type: object x-resourceId: CustomIntegrationApiKeys description: The integration key. properties: id: type: string description: The unique ID of the API key, used when signing JWTs or accessing the API using Basic Authentication. example: int_5e4b0f225aca01092928f917 displayName: allOf: - $ref: '#/components/schemas/displayName' description: The name of the API key. example: My custom key secret: type: string description: The secret of the API key, used when signing JWTs or accessing the API using Basic Authentication example: Ck1LjzzlUzvlCTtqAdQ2z1QukuBTrN3TIx integrationApiKeyResponse: type: object properties: key: $ref: '#/components/schemas/apiKey' webhookListResponse: type: object properties: webhooks: type: array description: List of webhooks associated with the integration. items: $ref: '#/components/schemas/webhook' webhookBody: type: object properties: target: $ref: '#/components/schemas/target' triggers: $ref: '#/components/schemas/triggers' includeFullUser: $ref: '#/components/schemas/includeFullUser' includeFullSource: $ref: '#/components/schemas/includeFullSource' webhookCreateBody: allOf: - $ref: '#/components/schemas/webhookBody' required: - target - triggers webhookResponse: type: object title: WebhookResponse properties: webhook: allOf: - $ref: '#/components/schemas/webhook' description: The webhook. enabled: type: boolean description: 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: type: string description: 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. example: 5ef21b132f21af34f088530e switchboard: type: object x-resourceId: Switchboards properties: id: type: string description: The unique ID of the switchboard. example: 5ef21b132f21af34f088530d enabled: $ref: '#/components/schemas/enabled' defaultSwitchboardIntegrationId: $ref: '#/components/schemas/defaultSwitchboardIntegrationId' required: - id - enabled switchboardListResponse: type: object properties: switchboards: type: array description: List of returned switchboards. items: $ref: '#/components/schemas/switchboard' switchboardResponse: type: object title: SwitchboardResponse properties: switchboard: allOf: - $ref: '#/components/schemas/switchboard' description: The switchboard. switchboardUpdateBody: type: object properties: enabled: $ref: '#/components/schemas/enabled' defaultSwitchboardIntegrationId: $ref: '#/components/schemas/defaultSwitchboardIntegrationId' deliverStandbyEvents: type: boolean description: Setting to determine if webhooks should be sent when the switchboard integration is not in control of a conversation (standby status) nextSwitchboardIntegrationId: type: string description: The switchboard integration id to which control of a conversation is passed / offered by default. example: 5ef21b86e933b7355c11c606 nullable: true messageHistoryCount: type: integer minimum: 1 maximum: 10 nullable: true description: Number of messages to include in the message history context. example: 5 switchboardIntegration: type: object x-resourceId: Switchboard Integrations properties: id: type: string description: The unique ID of the switchboard integration. example: 5ef21b86e933b7355c11c604 name: $ref: '#/components/schemas/name' integrationId: $ref: '#/components/schemas/switchboardIntegrationId' integrationType: $ref: '#/components/schemas/switchboardIntegrationType' deliverStandbyEvents: $ref: '#/components/schemas/deliverStandbyEvents' nextSwitchboardIntegrationId: $ref: '#/components/schemas/nextSwitchboardIntegrationId' messageHistoryCount: $ref: '#/components/schemas/messageHistoryCount' required: - id - name - integrationId - integrationType - deliverStandbyEvents switchboardIntegrationListResponse: type: object properties: switchboardIntegrations: type: array description: List of returned switchboard integrations. items: $ref: '#/components/schemas/switchboardIntegration' switchboardIntegrationCreateBody: type: object properties: name: $ref: '#/components/schemas/name' integrationId: allOf: - $ref: '#/components/schemas/switchboardIntegrationId' description: 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: allOf: - $ref: '#/components/schemas/switchboardIntegrationType' description: 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: allOf: - $ref: '#/components/schemas/deliverStandbyEvents' default: true nextSwitchboardIntegrationId: $ref: '#/components/schemas/nextSwitchboardIntegrationId' messageHistoryCount: $ref: '#/components/schemas/messageHistoryCount' required: - name switchboardIntegrationResponse: type: object title: SwitchboardIntegrationResponse properties: switchboardIntegration: allOf: - $ref: '#/components/schemas/switchboardIntegration' description: The switchboard integration. switchboardIntegrationUpdateBody: type: object properties: name: $ref: '#/components/schemas/name' integrationId: allOf: - $ref: '#/components/schemas/switchboardIntegrationId' description: 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: allOf: - $ref: '#/components/schemas/switchboardIntegrationType' description: 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: $ref: '#/components/schemas/deliverStandbyEvents' nextSwitchboardIntegrationId: $ref: '#/components/schemas/nextSwitchboardIntegrationId' messageHistoryCount: $ref: '#/components/schemas/messageHistoryCount' userTruncated: type: object properties: id: type: string description: The unique ID of the user. example: 7494535bff5cef41a15be74d authenticated: description: Whether or not the user has authenticated, either via JWT or via the Help Center readOnly: true type: boolean externalId: type: string description: | An optional ID that can also be used to retrieve the user. example: your-own-id nullable: true zendeskId: type: string description: | The ID that links a messaging user to its core Zendesk user counterpart. This ID can be used to fetch the core user record via the Zendesk Support API. example: '30045042291606' nullable: true brandId: type: string description: The user's brandId if the user is brand-separated. example: '9477922990333' nullable: true signedUpAt: type: string description: The date at which the user signed up. Must be ISO 8601 time format `YYYY-MM-DDThh:mm:ss.sssZ`. example: '2020-05-21T15:53:30.197Z' toBeRetained: type: boolean description: 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: type: object description: Object hosting user profile information. properties: givenName: type: string description: The user's given name (first name). minLength: 1 maxLength: 128 nullable: true example: Jane surname: type: string description: The user's surname (last name). minLength: 1 maxLength: 128 nullable: true example: Doe email: type: string description: The user's email address. format: email minLength: 1 maxLength: 128 nullable: true example: jane.doe@gmail.com avatarUrl: type: string description: The user's avatar. format: uri minLength: 1 maxLength: 2048 nullable: true example: https://s3.amazonaws.com/avatar.jpg locale: type: string description: End-user's locale information in BCP 47 format. minLength: 1 maxLength: 64 nullable: true example: fr-CA identity: type: object description: A connected user identity, such as an email. properties: type: type: string description: The type of identity. example: email value: type: string description: The identity value. minLength: 1 maxLength: 128 example: jane.doe@gmail.com verification: type: string description: The type of verification performed on the identity. example: embed user: allOf: - $ref: '#/components/schemas/userTruncated' - type: object x-resourceId: Users properties: signedUpAt: allOf: - $ref: '#/components/schemas/signedUpAt' toBeRetained: allOf: - $ref: '#/components/schemas/toBeRetained' profile: allOf: - $ref: '#/components/schemas/profile' metadata: allOf: - $ref: '#/components/schemas/metadata' nullable: false identities: description: The user's connected identities. readOnly: true type: array items: $ref: '#/components/schemas/identity' userListResponse: type: object properties: users: type: array description: List of returned users. items: $ref: '#/components/schemas/user' userCreateBody: type: object title: UserCreateBody properties: externalId: type: string minLength: 1 maxLength: 1024 description: | 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/). example: your-own-id brandId: type: string nullable: true minLength: 1 maxLength: 24 description: | If creating a brand-separated user, their brandId. example: '9477922990333' signedUpAt: $ref: '#/components/schemas/signedUpAt' toBeRetained: $ref: '#/components/schemas/toBeRetained' profile: $ref: '#/components/schemas/profile' metadata: $ref: '#/components/schemas/metadata' userResponse: type: object title: UserResponse properties: user: allOf: - $ref: '#/components/schemas/user' description: The user. userUpdateBody: type: object title: UserUpdateBody properties: signedUpAt: allOf: - $ref: '#/components/schemas/signedUpAt' toBeRetained: allOf: - $ref: '#/components/schemas/toBeRetained' profile: allOf: - $ref: '#/components/schemas/profile' metadata: $ref: '#/components/schemas/metadata' clientListResponse: type: object properties: clients: type: array description: List of returned clients. items: $ref: '#/components/schemas/client' meta: $ref: '#/components/schemas/meta' links: $ref: '#/components/schemas/links' matchCriteriaMailgun: allOf: - $ref: '#/components/schemas/matchCriteriaBase' - type: object description: The set of criteria used to determine the user's identity on a third-party channel. properties: type: type: string description: The channel type. default: mailgun address: type: string description: The user’s email address. example: steveb@channel5.com subject: type: string description: May be specified to set the subject for the outgoing email. default: New message from {appName} required: - address matchCriteriaMessagebird: allOf: - $ref: '#/components/schemas/matchCriteriaBase' - type: object description: The set of criteria used to determine the user's identity on a third-party channel. properties: type: type: string description: The channel type. default: messagebird phoneNumber: type: string description: | The user’s phone number. It must contain the + prefix and the country code. Examples of valid phone numbers: +1 212-555-2368, +12125552368, +1 212 555 2368. Examples of invalid phone numbers: 212 555 2368, 1 212 555 2368. example: '+15550001234' required: - phoneNumber matchCriteriaTwilio: allOf: - $ref: '#/components/schemas/matchCriteriaBase' - type: object description: The set of criteria used to determine the user's identity on a third-party channel. properties: type: type: string description: The channel type. default: twilio phoneNumber: type: string description: | The user’s phone number. It must contain the + prefix and the country code. Examples of valid phone numbers: +1 212-555-2368, +12125552368, +1 212 555 2368. Examples of invalid phone numbers: 212 555 2368, 1 212 555 2368. example: '+15550001234' required: - phoneNumber matchCriteriaWhatsapp: allOf: - $ref: '#/components/schemas/matchCriteriaBase' - type: object description: The set of criteria used to determine the user's identity on a third-party channel. properties: type: type: string description: The channel type. default: whatsapp phoneNumber: type: string description: | The user’s phone number. It must contain the + prefix and the country code. Examples of valid phone numbers: +1 212-555-2368, +12125552368, +1 212 555 2368. Examples of invalid phone numbers: 212 555 2368, 1 212 555 2368. example: '+15550001234' required: - phoneNumber matchCriteriaBase: type: object description: The set of criteria used to determine the user's identity on a third-party channel. properties: type: type: string description: The channel type. integrationId: type: string description: The ID of the integration to link. Must match the provided type. example: 582dedf230e788746891281a primary: type: boolean description: Flag indicating whether the client will become the primary for the target conversation once linking is complete. default: true required: - type - integrationId matchCriteria: oneOf: - $ref: '#/components/schemas/matchCriteriaMailgun' - $ref: '#/components/schemas/matchCriteriaMessagebird' - $ref: '#/components/schemas/matchCriteriaTwilio' - $ref: '#/components/schemas/matchCriteriaWhatsapp' discriminator: propertyName: type mapping: mailgun: '#/components/schemas/matchCriteriaMailgun' messagebird: '#/components/schemas/matchCriteriaMessagebird' twilio: '#/components/schemas/matchCriteriaTwilio' whatsapp: '#/components/schemas/matchCriteriaWhatsapp' description: The set of criteria used to determine the user's identity on a third-party channel. clientCreate: type: object properties: matchCriteria: $ref: '#/components/schemas/matchCriteria' confirmation: type: object title: Confirmation description: The confirmation options of the link request. properties: type: type: string description: The type of confirmation. enum: - immediate - userActivity - prompt message: allOf: - $ref: '#/components/schemas/messagePost' description: The message used to reach out to the user, if desired. Messages sent via this method can only be of type text and image. If actions are included they can only be of type link. The confirmation message will not be added to the user’s conversation. required: - type target: type: object title: Target description: The target conversation to attach the client to. properties: conversationId: type: string description: The conversation ID of the target conversation. example: 029c31f25a21b47effd7be90 required: - conversationId required: - matchCriteria - confirmation - target deviceListResponse: type: object properties: devices: type: array description: List of returned devices. items: $ref: '#/components/schemas/device' deviceResponse: type: object title: deviceResponse properties: device: allOf: - $ref: '#/components/schemas/device' description: The device. syncUserBody: type: object properties: survivingZendeskId: type: string description: | 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. example: '35436' appSubSchema: type: object description: The app that triggered the events. properties: id: type: string description: The unique ID of the app. example: 5e4af71a81966cfff3ef6550 webhookSubSchema: type: object description: The webhook that generated the payload. properties: id: type: string description: The unique ID of the webhook. version: type: string description: Schema version of the payload delivered to this webhook (v2). example: id: 582dedf230e788746891281a version: v2 eventSubSchema: type: object properties: id: type: string description: The unique ID of the event. May be used to ensure that an event is not processed twice in the case of a webhook that is re-tried due to an error or timeout. type: type: string description: The type of the event. Will match one of the subscribed triggers for your [webhook](#operation/CreateWebhook). createdAt: type: string description: A timestamp signifying when the event was generated. Formatted as `YYYY-MM-DDThh:mm:ss.SSSZ`. example: id: 0ca7d56ba7b2e081e479fe9e type: conversation:message createdAt: '2020-02-25T18:06:37.547Z' sourceWebhook: type: object properties: type: type: string description: An identifier for the channel from which a message originated. May include one of api, sdk, messenger, or any number of other channels. example: ios integrationId: type: string description: Identifier indicating which integration the message was sent from. For user messages only. originalMessageId: type: string description: Message identifier assigned by the originating channel. nullable: true originalMessageTimestamp: type: string description: A datetime string with the format YYYY-MM-DDThh:mm:ss.SSSZ representing when the third-party channel received the message. nullable: true client: allOf: - $ref: '#/components/schemas/client' description: The client from which the user authored the message or activity, if applicable. This field will only be present if the `includeFullSource` option is enabled for the webhook. nullable: true device: allOf: - $ref: '#/components/schemas/device' description: The device from which the user authored the message or activity, if applicable. This field will only be present if the `includeFullSource` option is enabled for the webhook nullable: true clientAddEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: | The conversation associated with the creation of the client. This field is only present when the reason is `channelLinking` and when attaching the client to a specific conversation. nullable: true user: allOf: - $ref: '#/components/schemas/userTruncated' description: The user associated with the client. client: allOf: - $ref: '#/components/schemas/client' description: The client that was just created. reason: type: string description: | The reason for which the client was added. * `channelLinking` - The client was created as a result of initiating a channel link. * `sdkLogin` - The client was created as a result of logging into an SDK device. * `authCode` - The client was created as a result of initializing an SDK client with an `authCode`. enum: - channelLinking - sdkLogin - authCode source: allOf: - $ref: '#/components/schemas/sourceWebhook' description: The source where this event originated from. This could be the API or an SDK device. title: client:add clientRemoveEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: | The conversation associated with the removal of the client. This field is only present when the reason is `theft`, `linkCancelled` or `linkFailed`. Note that for the `theft` reason, the conversation will not be present if it has been deleted. nullable: true user: allOf: - $ref: '#/components/schemas/userTruncated' description: The user associated with the client. client: allOf: - $ref: '#/components/schemas/client' description: The removed client. reason: type: string description: | The reason for which the client was removed. * `api` - The client was removed using the API. * `linkCancelled` - The user cancelled a channel link. * `linkFailed` - The client was removed after a channel link attempt failed. * `sdk` - The client was removed using the SDK. * `theft` - The client was transferred to another user due to a channel link. enum: - api - linkCancelled - linkFailed - sdk - theft error: type: object description: Object containing details of what went wrong. This field will only be present when the reason is `linkCancelled` or `linkFailed`. nullable: true source: allOf: - $ref: '#/components/schemas/sourceWebhook' description: The source where this event originated from. This could be the API or an SDK device. title: client:remove clientUpdateEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation which triggered a change in the client. user: allOf: - $ref: '#/components/schemas/userTruncated' description: The user associated with the client. client: allOf: - $ref: '#/components/schemas/client' description: The updated client. reason: type: string description: | The reason for which the client was updated. * `confirmed` - The client is now active and ready to use. * `blocked` - The user has unsubscribed from the conversation. * `unblocked` - A previously unsubscribed user resubscribed to the conversation. * `matched` - The channel found a user that matches the information provided. enum: - confirmed - blocked - unblocked - matched title: client:update campaign: type: object description: The campaign the user interacted with (if applicable). properties: id: type: string description: The unique ID of the campaign. example: de13bee15b51033b34162411 nullable: true sourceWithCampaignWebhook: allOf: - $ref: '#/components/schemas/sourceWebhook' - type: object properties: campaign: $ref: '#/components/schemas/campaign' referral: type: object description: | Data representing a referral object when a user is referred to a conversation. See the conversation referrals guide for more details. properties: code: type: string description: The referral’s identifier. details: type: object nullable: true description: Nested object containing additional information. properties: source: type: string description: The source of the referral - MESSENGER_CODE, ADS etc… example: MESSENGER_CODE type: type: string description: The type of referral, typically OPEN-THREAD. example: OPEN-THREAD adId: type: string nullable: true description: If the referral came from an ad, this field will be present with the ad’s Id. example: '4216212847577' conversationCreateEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation that was created. creationReason: type: string description: | The reason why the conversation was created, if applicable. * `linkRequest` - The conversation was created in order to generate a link request to transfer the user to a different channel. * `message` - The conversation was created because a message was sent. * `none` - The conversation was not created for a specific purpose. Used primarily when a conversation is created via the Create Conversation API. * `notification` - The conversation was created by a call to the Notification API. * `prechatCapture` - The conversation was created because the user completed a prechat capture form in the Web Messenger. * `startConversation` - The conversation was created because of a call to the startConversation API on one of the SDK integrations, or a start conversation event was triggered from a messaging channel. * `proactiveMessaging` - The conversation was created because the user interacted with a campaign. enum: - linkRequest - message - none - notification - prechatCapture - startConversation - proactiveMessaging source: allOf: - $ref: '#/components/schemas/sourceWithCampaignWebhook' description: The source of the creation. user: allOf: - $ref: '#/components/schemas/user' description: The user associated with the conversation. Only present if the created conversation was of type personal. For sdkGroup conversations, the list of participants can be fetched using the List Participants API, if required. nullable: true referral: allOf: - $ref: '#/components/schemas/referral' description: Referral information, if applicable. nullable: true title: conversation:create conversationJoinEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation in which the user was added. user: allOf: - $ref: '#/components/schemas/userTruncated' description: The user that joined the conversation. title: conversation:join conversationLeaveEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation in which the user was removed. user: allOf: - $ref: '#/components/schemas/userTruncated' description: The user that left the conversation. title: conversation:leave conversationRemoveEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation that was deleted. title: conversation:remove conversationMessageDeliveryPayload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: user: allOf: - $ref: '#/components/schemas/user' description: The user associated with the conversation. conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation in which the message was sent. message: type: object properties: id: type: string description: A string representing the ID of the message. description: The message that was sent. destination: type: object description: A nested object representing the destination of the message. properties: type: type: string description: An identifier for the channel to which a message was sent to. May include one of "web", "ios", "android", "messenger", "viber", "telegram", "wechat", "line", "twilio", "api", "notification", or any other channel. integrationId: type: string description: Identifier indicating which integration the message was sent to. externalMessages: type: array nullable: true description: An array of objects representing the third-party messages associated with the event. The order of the external messages is not guaranteed to be the same across the different triggers. Note that some channels don’t expose message IDs, in which case this field will be unset. items: type: object properties: id: type: string description: A string representing the ID of the external message. isFinalEvent: type: boolean description: A boolean indicating whether the webhook is the final one for the `message.id` and `destination.type` pair. conversationMessageDeliveryChannelEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: $ref: '#/components/schemas/conversationMessageDeliveryPayload' title: conversation:message:delivery:channel conversationMessageDeliveryFailureEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: allOf: - $ref: '#/components/schemas/conversationMessageDeliveryPayload' - type: object properties: error: type: object description: A nested object representing the error associated with the delivery failure. properties: code: type: string description: A string representing the error code associated with the error. message: type: string description: The description associated with the error. title: conversation:message:delivery:failure conversationMessageDeliveryUserEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: $ref: '#/components/schemas/conversationMessageDeliveryPayload' title: conversation:message:delivery:user authorWebhook: type: object description: The author of the activity. properties: type: type: string description: The `type` of the author. enum: - business - user userId: type: string description: The id of the user. Only supported when author `type` is `user`. example: 5963c0d619a30a2e00de36b8 user: allOf: - $ref: '#/components/schemas/user' description: The user that authored the message or activity. `profile` is included in the payload if the `includeFullUser` option is enabled. required: - type messageWebhook: type: object properties: id: type: string description: The unique ID of the message. example: 5e552ef595e5206375bb835d received: type: string description: A datetime string with the format `YYYY-MM-DDThh:mm:ss.SSSZ` representing when Sunshine Conversations received the message. example: '2019-03-21T18:48:52.760Z' author: $ref: '#/components/schemas/authorWebhook' content: allOf: - $ref: '#/components/schemas/content' description: The content of the message. source: allOf: - $ref: '#/components/schemas/source' - type: object properties: campaign: $ref: '#/components/schemas/campaign' quotedMessage: allOf: - $ref: '#/components/schemas/quotedMessage' description: The quoted message is currently only available for WhatsApp and Web Messenger `formResponse` messages. nullable: true metadata: allOf: - $ref: '#/components/schemas/metadata' nullable: true deleted: type: boolean description: true if the message serves as a placeholder for one that has been deleted. nullable: true conversationMessageEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation in which the message was sent. message: allOf: - $ref: '#/components/schemas/messageWebhook' description: The message that was sent. recentNotifications: type: array description: Messages sent with the Notification API since the last user message. items: $ref: '#/components/schemas/messageWebhook' title: conversation:message postbackWebhook: type: object properties: payload: type: string description: The payload associated with the postback. metadata: $ref: '#/components/schemas/metadata' conversationPostbackEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: postback: allOf: - $ref: '#/components/schemas/postbackWebhook' description: The postback associated with the event. conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation linked to the postback. user: allOf: - $ref: '#/components/schemas/user' description: The user that triggered the postback. source: allOf: - $ref: '#/components/schemas/sourceWithCampaignWebhook' description: The source of the postback. title: conversation:postback activity: allOf: - $ref: '#/components/schemas/activityTypes' - type: object properties: source: allOf: - $ref: '#/components/schemas/sourceWebhook' description: The source of the activity. author: $ref: '#/components/schemas/authorWebhook' conversationReadEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation in which the message was read. activity: allOf: - $ref: '#/components/schemas/activity' - type: object properties: type: type: string description: The type of activity. default: conversation:read description: The activity that was sent. title: conversation:read conversationReferralEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation a user lands in after being referred. See the conversation referrals guide for more details. user: allOf: - $ref: '#/components/schemas/user' description: The user associated with the conversation. source: allOf: - $ref: '#/components/schemas/sourceWithCampaignWebhook' description: The source of the referral. referral: allOf: - $ref: '#/components/schemas/referral' title: conversation:referral conversationTypingEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation in which the activity was sent. activity: allOf: - $ref: '#/components/schemas/activity' - type: object properties: type: type: string description: The type of activity. description: The activity that was sent. title: conversation:typing switchboardAcceptControl: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation from which the switchboard event was fired. Will include an `activeSwitchboardIntegration` representing the integration that has just accepted control. metadata: $ref: '#/components/schemas/metadata' title: switchboard:acceptControl switchboardAcceptControlFailure: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: error: type: object description: Object containing details of what went wrong. conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation from which the switchboard event was fired. metadata: $ref: '#/components/schemas/metadata' title: switchboard:acceptControl:failure switchboardOfferControl: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation from which the switchboard event was fired. On success, the payload will include an `activeSwitchboardIntegration`, representing the integration from which control is being offered, and a `pendingSwitchboardIntegration`, representing the integration being offered control. metadata: $ref: '#/components/schemas/metadata' title: switchboard:offerControl switchboardOfferControlFailure: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: error: type: object description: Object containing details of what went wrong. conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation from which the switchboard event was fired. metadata: $ref: '#/components/schemas/metadata' title: switchboard:offerControl:failure switchboardPassControl: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation from which the switchboard event was fired. On success, the payload will include an `activeSwitchboardIntegration`, representing the switchboard integration that is now in control of the conversation. metadata: $ref: '#/components/schemas/metadata' reason: type: string description: Reason for the pass control action, if applicable. enum: - ticketClosed - transferToEmail title: switchboard:passControl switchboardPassControlFailure: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: error: type: object description: Object containing details of what went wrong. conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation from which the switchboard event was fired. metadata: $ref: '#/components/schemas/metadata' title: switchboard:passControl:failure switchboardReleaseControl: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: conversation: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation from which the switchboard event was fired. The payload will omit `activeSwitchboardIntegration`, representing that no switchboard integration is in control of the conversation. metadata: $ref: '#/components/schemas/metadata' reason: type: string description: Reason for the release control action, if applicable. enum: - ticketClosed - transferToEmail title: switchboard:releaseControl userMergeEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: mergedUsers: type: object description: Contains information about the users that were merged together. properties: surviving: allOf: - $ref: '#/components/schemas/user' description: The user that now represents the merged user object. discarded: allOf: - $ref: '#/components/schemas/user' description: The user that was unified into the surviving user object. mergedConversations: type: object description: Contains information about the conversations that were merged together as a result of the operation, if applicable. If no conversations were merged, this property is omitted. properties: surviving: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation that now represents the merged conversation object. discarded: allOf: - $ref: '#/components/schemas/conversationTruncated' description: The conversation that was unified into the surviving conversation object. nullable: true mergedClients: type: object description: Contains information about the clients that were merged together as a result of the operation, if applicable. If no clients were merged, this property is omitted. properties: surviving: allOf: - $ref: '#/components/schemas/client' description: The client that already existed before the merge started. discarded: allOf: - $ref: '#/components/schemas/client' description: The pending client that was discarded during the merge event. nullable: true discardedMetadata: allOf: - $ref: '#/components/schemas/metadata' description: A flat object with the set of metadata properties that were discarded when merging the two users. This should contain values only if the combined metadata fields exceed the 4KB limit. nullable: true reason: type: string description: | The reason for which the users merged. * `api` - The users were merged using the API. * `channelLinking` - The users were merged as a result of initiating a channel link. * `sdkLogin` - The users were merged as a result of logging into an SDK device. enum: - api - channelLinking - sdkLogin title: user:merge userUpdateEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: user: allOf: - $ref: '#/components/schemas/user' description: The updated user. reason: type: string description: | The reason why the user was updated, if applicable. * `authentication` - An unauthenticated user became an [authenticated](https://developer.zendesk.com/documentation/conversations/messaging-platform/users/intro-to-users/) user. * `localeDetection` - A user was updated as a result of automated locale detection on messages sent. enum: - authentication - localeDetection source: allOf: - $ref: '#/components/schemas/sourceWebhook' description: The source of the creation. title: user:update userRemoveEvent: allOf: - $ref: '#/components/schemas/eventSubSchema' - type: object properties: payload: type: object description: The payload of the event. The contents of this object depend on the type of event. properties: user: allOf: - $ref: '#/components/schemas/userTruncated' description: The user that was removed. title: user:remove parameters: pageQuery: name: page in: query description: Contains parameters for applying cursor pagination. schema: $ref: '#/components/schemas/page' style: deepObject explode: true appFilterQuery: name: filter in: query description: Contains parameters for filtering the results. schema: type: object title: appListFilter properties: serviceAccountId: type: string description: When specified, lists only the apps that the service account has access to. style: deepObject explode: true appId: name: appId in: path description: Identifies the app. schema: type: string example: 5d8cff3cd55b040010928b5b required: true keyId: name: keyId in: path description: The id of the key. required: true schema: type: string example: int_5d8cff3cd55b040010928b5b accessQuery: name: access in: query description: The access level for the attachment. Currently the only available access level is public. Private is not supported. schema: type: string example: public default: public required: true forQuery: name: for in: query description: Specifies the intended container for the attachment, to enable automatic attachment deletion (on deletion of associated message, conversation or user). For now, only message is supported. See [Attachments for Messages](#section/Attachments-for-Messages) for details. schema: type: string example: message conversationIdQuery: name: conversationId in: query description: Links the attachment getting uploaded to the conversation ID. schema: type: string example: c616a583e4c240a871818541 conversationFilterQuery: name: filter in: query description: Contains parameters for filtering the results. schema: type: object title: conversationListFilter properties: userId: type: string description: The user's id. One of `userId` or `userExternalId` is required, but not both. userExternalId: type: string description: The external Id of the user. One of `userId` or `userExternalId` is required, but not both. style: deepObject explode: true required: true conversationId: name: conversationId in: path description: Identifies the conversation. schema: type: string example: 029c31f25a21b47effd7be90 required: true messageId: name: messageId in: path description: The id of the message. schema: type: string example: 029c31f25a21b47effd7be90 required: true integrationFilterQuery: name: filter in: query description: Contains parameters for filtering the results. schema: type: object title: integrationListFilter properties: types: type: string description: Comma-separated list of types to return. If omitted, all types are returned. example: android,ios style: deepObject explode: true integrationId: name: integrationId in: path description: The id of the integration. schema: type: string example: 029c31f25a21b47effd7be90 required: true webhookId: name: webhookId in: path description: The id of the webhook. schema: type: string example: 029c31f25a21b47effd7be90 required: true switchboardId: name: switchboardId in: path description: Identifies the switchboard. schema: type: string example: 5d8cff3cd55b040010928b5b required: true switchboardIntegrationId: name: switchboardIntegrationId in: path description: Identifies the switchboard integration. schema: type: string example: 5d8cff3cd55b040010928b5b required: true userFilterQuery: name: filter in: query description: Contains parameters for filtering the results. schema: type: object title: userListFilter properties: identities.email: type: string description: The user's email. Will match users based on emails found in the `identities` array. This parameter will not match against emails stored in `profile.email`. required: true style: deepObject explode: true required: true brandIdQuery: name: brandId in: query description: Identifies the brand. Provide this when querying a brand-separated user by externalId or identity. schema: type: string example: '9477922990333' userIdOrExternalId: in: path name: userIdOrExternalId description: The user's id or externalId. required: true schema: type: string example: 42589ad070d43be9b00ff7e5 clientId: name: clientId in: path description: The client's id. required: true schema: type: string example: 5d8cff3cd55b040010928b5b deviceId: name: deviceId in: path description: The device's id. required: true schema: type: string example: 5d8cff3cd55b040010928b5b zendeskId: in: path name: zendeskId description: | The ID that links a messaging user to its core Zendesk user counterpart. This ID can be used to fetch the core user record via the Zendesk Support API. required: true schema: type: string example: '35436' clientIdQuery: name: client_id in: query description: Your integration’s unique identifier schema: type: string example: 5e4af71a81966cfff3ef6550 required: true responseTypeQuery: name: response_type in: query description: For now the only acceptable value is code. schema: type: string example: code required: true stateQuery: name: state in: query description: You may pass in any arbitrary string value here which will be returned to you along with the code via browser redirect. schema: type: string example: Pending redirectUriQuery: name: redirect_uri in: query description: 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. schema: type: string example: https://example.org examples: listApps: value: apps: - id: 67a0e55ef0305f4a391e9d69 displayName: My Test App settings: appLocalizationEnabled: true echoPostback: false maskCreditCardNumbers: true multiConvoEnabled: false useAnimalNames: false createApp: value: app: id: 67a0e55ef0305f4a391e9d69 displayName: My Test App settings: appLocalizationEnabled: true echoPostback: false maskCreditCardNumbers: true multiConvoEnabled: false useAnimalNames: false getApp: value: app: id: 67a0e55ef0305f4a391e9d69 displayName: My Test App settings: appLocalizationEnabled: true echoPostback: false maskCreditCardNumbers: true multiConvoEnabled: false useAnimalNames: false emptyResponse: value: {} updateApp: value: app: id: 67a0e55ef0305f4a391e9d69 displayName: My Test App settings: appLocalizationEnabled: true echoPostback: false maskCreditCardNumbers: true multiConvoEnabled: false useAnimalNames: false listAppKeys: value: keys: - id: app_67a0e949f0305f4a391e9d97 displayName: My Test Key secret: 2vErhBhv81FZ5YXbC5XElVcnoNSqz0XjhqSYII4AOT3GCA5UojDCT07Z9NG_4PVzcxv-Zdd7IpeBL-RcXvfOyw createAppKey: value: key: id: app_67a0e949f0305f4a391e9d97 displayName: My Test Key secret: 2vErhBhv81FZ5YXbC5XElVcnoNSqz0XjhqSYII4AOT3GCA5UojDCT07Z9NG_4PVzcxv-Zdd7IpeBL-RcXvfOyw getAppKey: value: key: id: app_67a0e949f0305f4a391e9d97 displayName: My Test Key secret: 2vErhBhv81FZ5YXbC5XElVcnoNSqz0XjhqSYII4AOT3GCA5UojDCT07Z9NG_4PVzcxv-Zdd7IpeBL-RcXvfOyw uploadAttachment: value: attachment: mediaUrl: https://subdomain.zendesk.com/sc/attachments/v2/01JK699PBZ645YAFJW2RF45F0B/my_file.jpeg mediaType: image/jpeg listConversations: value: conversations: - id: 67a0ecf8f0305f4a391e9db1 type: personal isDefault: false lastUpdatedAt: '2025-02-03T16:21:12.308Z' createdAt: '2025-02-03T16:21:12.308Z' createConversation: value: conversation: id: 67a0ecf8f0305f4a391e9db1 type: personal isDefault: false lastUpdatedAt: '2025-02-03T16:21:12.308Z' createdAt: '2025-02-03T16:21:12.308Z' getConversation: value: conversation: id: 67a0ecf8f0305f4a391e9db1 type: personal isDefault: false lastUpdatedAt: '2025-02-03T16:21:12.308Z' createdAt: '2025-02-03T16:21:12.308Z' updateConversation: value: conversation: id: 67a0ecf8f0305f4a391e9db1 type: personal isDefault: false lastUpdatedAt: '2025-02-03T16:21:12.308Z' createdAt: '2025-02-03T16:21:12.308Z' joinConversation: value: participant: id: 67a0ee3880e2647cbb7a9c97 userId: 67179a2930a150d5adc4d51f unreadCount: 0 clientAssociations: - type: sdk clientId: 67a0ee38f0305f4a391e9def listParticipants: value: participants: - id: 67a0ecf880e2647cbb7a9701 userId: 67179a2930a150d5adc4d51f unreadCount: 0 clientAssociations: [] meta: hasMore: false listMessages: value: messages: - id: 67a10c0bf0305f4a391e9e51 received: '2025-02-03T18:33:47.466Z' author: type: business avatarUrl: https://www.gravatar.com/avatar/00000000000000000000000000000000.png?s=200&d=mm content: type: text text: Hello World source: type: api:conversations meta: hasMore: false text: value: author: type: business content: type: text text: Hello! carousel: value: author: type: business content: type: carousel items: - title: Tacos description: Get your tacos today! mediaUrl: https://example.org/image.jpg altText: A giant taco size: compact actions: - text: Select type: postback payload: TACOS - text: More info type: link uri: https://example.org - title: Ramen description: Get your ramen today! mediaUrl: https://example.org/image.jpg altText: A chicken vegetable ramen bowl size: compact actions: - text: Select type: postback payload: RAMEN - text: More info type: link uri: https://example.org file: value: author: type: business content: type: file text: Here's our FAQ! mediaUrl: https://example.org/FAQ.pdf altText: FAQ.pdf form: value: author: type: business content: type: form blockChatInput: true fields: - type: text name: full_name label: Your name? placeholder: Type your name... minSize: 1 maxSize: 30 - type: email name: email_address label: Your email? placeholder: email@example.com image: value: author: type: business content: type: image text: Hello! mediaUrl: https://example.org/image.jpg altText: A wonderful image list: value: author: type: business content: type: list items: - title: Tacos description: Get your tacos today! mediaUrl: https://example.org/image.jpg size: compact actions: - text: Select type: postback payload: TACOS - text: More info type: link uri: https://example.org - title: Ramen description: Get your ramen today! mediaUrl: https://example.org/image.jpg size: compact actions: - text: Select type: postback payload: RAMEN - text: More info type: link uri: https://example.org location: value: author: type: business content: type: location coordinates: lat: 45.5261583 long: -73.595346 location: address: 5333 avenue Casgrain name: Zendesk Montréal whatsappTemplate: value: author: type: business schema: whatsapp content: type: template template: namespace: XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX name: hello_world language: policy: deterministic code: en_US component: - type: header parameters: - type: image image: link: https://image.jpg - type: body parameters: - type: text text: My User Name - type: text text: My Agent Name text-2: value: 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 carousel-2: value: messages: - id: 5f748c1a2b5315fc007e7977 received: '2020-09-30T13:46:02.733Z' author: type: business avatarUrl: https://www.gravatar.com/image.jpg content: type: carousel text: |- 1. Tacos Get your tacos today! More info: https://example.org 2. Ramen Get your ramen today! More info: https://example.org items: - title: Tacos description: Get your tacos today! mediaUrl: https://example.org/image.jpg altText: A giant taco mediaType: text/html; charset=UTF-8 size: compact actions: - text: Select type: postback payload: TACOS uri: '' - text: More info type: link uri: https://example.org - title: Ramen description: Get your ramen today! mediaUrl: https://example.org/image.jpg altText: A chicken vegetable ramen bowl mediaType: text/html; charset=UTF-8 size: compact actions: - text: Select type: postback payload: RAMEN uri: '' - text: More info type: link uri: https://example.org source: type: api:conversations file-2: value: messages: - id: 5f748c1a2b5315fc007e7977 received: '2020-09-30T13:46:02.733Z' author: type: business avatarUrl: https://www.gravatar.com/image.jpg content: type: file text: Here's our FAQ! mediaUrl: https://example.org/FAQ.pdf altText: FAQ.pdf mediaType: application/pdf mediaSize: 627328 source: type: api:conversations form-2: value: messages: - id: 5f748c1a2b5315fc007e7977 received: '2020-09-30T13:46:02.733Z' author: type: business avatarUrl: https://www.gravatar.com/image.jpg content: type: form submitted: false blockChatInput: true fields: - type: text name: full_name label: Your name? placeholder: Type your name... minSize: 1 maxSize: 30 - type: email name: email_address label: Your email? placeholder: email@example.com source: type: api:conversations image-2: value: messages: - id: 5f748c1a2b5315fc007e7977 received: '2020-09-30T13:46:02.733Z' author: type: business avatarUrl: https://www.gravatar.com/image.jpg content: type: image text: Hello! mediaUrl: https://example.org/image.jpg altText: A wonderful image mediaType: image/jpg mediaSize: 627328 source: type: api:conversations list-2: value: messages: - id: 5f748c1a2b5315fc007e7977 received: '2020-09-30T13:46:02.733Z' author: type: business avatarUrl: https://www.gravatar.com/image.jpg content: type: list text": |- 1. Tacos Get your tacos today! More info: https://example.org 2. Ramen Get your ramen today! More info: https://example.org items: - title: Tacos description: Get your tacos today! mediaUrl: https://example.org/image.jpg mediaType: text/html; charset=UTF-8 size: compact actions: - text: Select type: postback payload: TACOS uri: '' - text: More info type: link uri: https://example.org - title: Ramen description: Get your ramen today! mediaUrl: https://example.org/image.jpg mediaType: text/html; charset=UTF-8 size: compact actions: - text: Select type: postback payload: RAMEN uri: '' - text: More info type: link uri: https://example.org source: type: api:conversations location-2: value: messages: - id: 5f748c1a2b5315fc007e7977 received: '2020-09-30T13:46:02.733Z' author: type: business avatarUrl: https://www.gravatar.com/image.jpg content: type: location text: |- Location shared: https://maps.google.com/maps?q=45.5261583,-73.595346 coordinates: lat: 45.5261583 long: -73.595346 location: address: 5333 avenue Casgrain name: Zendesk Montréal source: type: api:conversations conversionEvents: value: conversionEvents: datasetId: 1234567890123456 eventsReceived: 1 listIntegrations: value: integrations: - id: 5e4af71a81966cfff3ef6550 type: android status: active displayName: Android SDK meta: hasMore: false createIntegration: value: integration: id: 5e4af71a81966cfff3ef6550 type: android status: active displayName: Android SDK getIntegration: value: integration: id: 5e4af71a81966cfff3ef6550 type: android status: active displayName: Android SDK updateIntegration: value: integration: id: 5e4af71a81966cfff3ef6550 type: android status: active displayName: Android SDK listIntegrationKeys: value: keys: - id: int_67a1110ef0305f4a391e9f01 displayName: My Test Key secret: JWSooRf7mjKYQereu5ueIjxKdclNs7cdCDaT7bGHEitHFUbNxFb8C0Cwi0s7SG0vhjMDef_w5d-TVetWHanIBA createIntegrationKey: value: key: id: int_67a1110ef0305f4a391e9f01 displayName: My Test Key secret: JWSooRf7mjKYQereu5ueIjxKdclNs7cdCDaT7bGHEitHFUbNxFb8C0Cwi0s7SG0vhjMDef_w5d-TVetWHanIBA getIntegrationKey: value: key: id: int_67a1110ef0305f4a391e9f01 displayName: My Test Key secret: JWSooRf7mjKYQereu5ueIjxKdclNs7cdCDaT7bGHEitHFUbNxFb8C0Cwi0s7SG0vhjMDef_w5d-TVetWHanIBA listWebhooks: value: webhooks: - id: 5e554d2cac66fb73a3c01871 version: v2 target: https://example.com/callback triggers: - conversation:read - conversation:message secret: 8564b3e6a8b20a4bdb68b05ce9bc5936 includeFullUser: false includeFullSource: false createWebhook: value: webhook: id: 5e554d2cac66fb73a3c01871 version: v2 target: https://example.com/callback triggers: - conversation:read - conversation:message secret: 8564b3e6a8b20a4bdb68b05ce9bc5936 includeFullUser: false includeFullSource: false getWebhook: value: webhook: id: 5e554d2cac66fb73a3c01871 version: v2 target: https://example.com/callback triggers: - conversation:read - conversation:message secret: 8564b3e6a8b20a4bdb68b05ce9bc5936 includeFullUser: false includeFullSource: false updateWebhook: value: webhook: id: 5e554d2cac66fb73a3c01871 version: v2 target: https://example.com/callback triggers: - conversation:read - conversation:message secret: 8564b3e6a8b20a4bdb68b05ce9bc5936 includeFullUser: false includeFullSource: false listSwitchboards: value: switchboards: - id: 5ef21b132f21af34f088530d enabled: false createSwitchboard: value: switchboard: id: 5ef21b132f21af34f088530d enabled: false updateSwitchboard: value: switchboard: id: 5ef21b132f21af34f088530d enabled: false listSwitchboardIntegrations: value: switchboardIntegrations: - id: 5ef21b86e933b7355c11c604 name: zd-agentWorkspace integrationId: 5ef21b86e933b7355c11c605 integrationType: zd:agentWorkspace deliverStandbyEvents: false createSwitchboardIntegration: value: switchboardIntegration: id: 5ef21b86e933b7355c11c604 name: zd-agentWorkspace integrationId: 5ef21b86e933b7355c11c605 integrationType: zd:agentWorkspace deliverStandbyEvents: false updateSwitchboardIntegration: value: switchboardIntegration: id: 5ef21b86e933b7355c11c604 name: zd-agentWorkspace integrationId: 5ef21b86e933b7355c11c605 integrationType: zd:agentWorkspace deliverStandbyEvents: false listUsers: value: users: - id: 67a11490f0305f4a391e9f8a externalId: your-own-id zendeskId: '35436' brandId: '9477922990333' signedUpAt: '2025-02-03T19:10:08.152Z' hasPaymentInfo: false identities: - type: email value: sue@example.org verification: sso profile: locale: en localeOrigin: zendeskAccount metadata: {} createUser: value: user: id: 67a11490f0305f4a391e9f8a externalId: your-own-id brandId: '9477922990333' signedUpAt: '2025-02-03T19:10:08.152Z' hasPaymentInfo: false identities: [] profile: locale: en localeOrigin: zendeskAccount metadata: {} getUser: value: user: id: 67a11490f0305f4a391e9f8a externalId: your-own-id zendeskId: '35436' brandId: '9477922990333' signedUpAt: '2025-02-03T19:10:08.152Z' hasPaymentInfo: false identities: [] profile: locale: en localeOrigin: zendeskAccount metadata: {} updateUser: value: user: id: 67a11490f0305f4a391e9f8a externalId: your-own-id brandId: '9477922990333' signedUpAt: '2025-02-03T19:10:08.152Z' hasPaymentInfo: false identities: [] profile: locale: en localeOrigin: zendeskAccount metadata: {} listClients: value: clients: - id: 67a0ee38f0305f4a391e9def type: sdk status: active lastSeen: '2025-02-03T16:26:32.575Z' linkedAt: '2025-02-03T16:26:32.575Z' meta: hasMore: false whatsapp: value: matchCriteria: type: whatsapp integrationId: 582dedf230e788746891281a primary: true phoneNumber: +1 212-555-2368 confirmation: type: immediate target: conversationId: 029c31f25a21b47effd7be90 mailgun: value: matchCriteria: type: mailgun integrationId: 582dedf230e788746891281a primary: true address: steveb@channel5.com subject: New message from {appName} confirmation: type: immediate target: conversationId: 029c31f25a21b47effd7be90 messagebird: value: matchCriteria: type: messagebird integrationId: 582dedf230e788746891281a primary: true phoneNumber: +1 212-555-2368 confirmation: type: immediate target: conversationId: 029c31f25a21b47effd7be90 twilio: value: matchCriteria: type: twilio integrationId: 582dedf230e788746891281a primary: true phoneNumber: +1 212-555-2368 confirmation: type: immediate target: conversationId: 029c31f25a21b47effd7be90 createClient: value: client: id: 67a11639f0305f4a391ea02d integrationId: 5e8b49d936c1df272e8e1460 type: whatsapp status: pending listDevices: value: 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' getDevice: value: 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' deleteUserPersonalInformation: value: user: id: 67a11490f0305f4a391e9f8a externalId: your-own-id brandId: '9477922990333' signedUpAt: '2025-02-03T19:10:08.152Z' hasPaymentInfo: false identities: [] profile: {} metadata: {} syncUser: value: 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: {} getToken: value: access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFwcF82N2EyNDBlY2M0OTk3OTAzNTg0YTNjNDgiLCJhenAiOiJzaG9wbGlmdGVyIn0.eyJzY29wZSI6ImludGVncmF0aW9uIiwiYXBwSWQiOiI1Njk4ZWRiZjJhNDNiZDA4MWJlOTgyZjEiLCJpYXQiOjE3Mzg2ODY3MDF9.vm9Bn84ALC9phe-6oo9-qZtm7LiGzZPVmmQd1mpeY7Y token_type: Bearer clientAddEvent: value: 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 clientRemoveEvent: value: app: id: 60bf823452c2a718162f986a webhook: id: 612905a67821c3f206d6909f version: v2 events: - id: 61290a6cc64b3af1ff868715 createdAt: '2021-08-27T15:53:16.591Z' type: client:remove payload: user: id: 6a2343df57be6fe0f98efc33 authenticated: false client: integrationId: 60bfc8fa67951336472cc57a type: twilio externalId: '+15140000000' id: 61290a4f7821c3f206d690a3 displayName: +1 514-000-0000 status: active info: phoneNumber: '+15140000000' city: MONTREAL country: CA state: QC raw: FromZip: '' FromState: QC FromCity: MONTREAL FromCountry: CA From: '+15140000000' lastSeen: '2021-08-27T15:53:06.721Z' linkedAt: '2021-08-27T15:52:47.998Z' reason: sdk source: type: web integrationId: 60bf824952c2a718162f989c clientUpdateEvent: value: app: id: 60bf823452c2a718162f986a webhook: id: 612905a67821c3f206d6909f version: v2 events: - id: 61290a62c64b3af1ff868714 createdAt: '2021-08-27T15:53:06.744Z' type: client:update payload: conversation: id: c2c8710dedf8f26ee6e9a68f type: personal user: id: 6a2343df57be6fe0f98efc33 authenticated: false client: integrationId: 60bfc8fa67951336472cc57a type: twilio externalId: '+15140000000' id: 61290a4f7821c3f206d690a3 displayName: +1 514-000-0000 status: active info: phoneNumber: '+15140000000' city: MONTREAL country: CA state: QC raw: FromZip: '' FromState: QC FromCity: MONTREAL FromCountry: CA From: '+15140000000' lastSeen: '2021-08-27T15:53:06.721Z' linkedAt: '2021-08-27T15:52:47.998Z' reason: confirmed conversationCreateEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:create payload: conversation: id: f52b01137aa6c250bc7251fa type: personal metadata: lang: en-ca activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom user: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: true creationReason: prechatCapture source: type: web integrationId: 5ecff63ffc3ab25f4561c8a0 conversationJoinEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:join payload: conversation: id: f52b01137aa6c250bc7251fa type: sdkGroup activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom user: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: true conversationLeaveEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:leave payload: conversation: id: f52b01137aa6c250bc7251fa type: sdkGroup activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom user: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: true conversationRemoveEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:remove payload: conversation: id: f52b01137aa6c250bc7251fa type: sdkGroup activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom conversationMessageDeliveryChannelEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:message:delivery:channel payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom user: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: true destination: type: telegram integrationId: 5ec69c6e12dda33be985cb1a externalMessages: - id: '371' message: id: 5f74a31c2b5315fc007e7997 isFinalEvent: true conversationMessageDeliveryFailureEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:message:delivery:failure payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom user: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: false destination: type: twilio integrationId: 5ecc061987d4d413774a8131 message: id: 5f74be6256be263abf0ffd5f isFinalEvent: true error: code: uncategorized_error message: Unsupported message type `form` conversationMessageDeliveryUserEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:message:delivery:user payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom user: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: true destination: type: twilio integrationId: 5ecc061987d4d413774a8131 externalMessages: - id: SM900c83b124b6467eb6db835a969d7374 message: id: 5f74b82c56be263abf0ffd50 isFinalEvent: true conversationMessageEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:message payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom message: id: 5f74c7d84a146f3abd72af1d received: '2020-09-30T18:00:56.820Z' author: userId: 26508c10541a4b0ff472e5e2 avatarUrl: https://s3.amazonaws.com/avatar.jpg displayName: Steve Rogers type: user user: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: true content: type: text text: hello source: integrationId: 5ec69c6e12dda33be985cb1a originalMessageId: '374' originalMessageTimestamp: '2020-09-30T18:00:56.000Z' type: telegram conversationPostbackEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:postback payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom postback: payload: Greet user: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: true source: type: telegram integrationId: 5ec69c6e12dda33be985cb1a conversationReadEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:read payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom activity: type: conversation:read author: type: user userId: b5a0f8de1fd4198a96faa0af user: id: b5a0f8de1fd4198a96faa0af authenticated: false source: type: web integrationId: 5ecff63ffc3ab25f4561c8a0 conversationReferralEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a type: conversation:referral payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom user: id: 26508c10541a4b0ff472e5e2 externalId: 912382197 authenticated: true source: type: web integrationId: 5ecff63ffc3ab25f4561c8a0 referral: {} conversationTypingEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: conversation:typing payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom activity: type: typing:start author: type: user userId: 7283cdd6f586679a5fc43cfb user: id: 7283cdd6f586679a5fc43cfb authenticated: false source: type: web integrationId: 5ecff63ffc3ab25f4561c8a0 switchboardAcceptControlEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: switchboard:acceptControl payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom switchboardAcceptControlFailureEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: switchboard:acceptControl:failure payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom error: code: switchboard_invalid_action message: There is no pendingSwitchboardIntegration switchboardOfferControlEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: switchboard:offerControl payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom pendingSwitchboardIntegration: id: 5eece1cacdbffb08f5c3ed43 name: human integrationId: 5f11a65ae4e987667c2051d2 integrationType: custom switchboardOfferControlFailureEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: switchboard:offerControl:failure payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom error: code: switchboard_invalid_target message: Cannot offer control to the active switchboard integration. switchboardPassControlEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: switchboard:passControl payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom switchboardPassControlFailureEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: switchboard:passControl:failure payload: conversation: id: f52b01137aa6c250bc7251fa type: personal activeSwitchboardIntegration: id: 5eecde2dcdbffb08f5c3ed37 name: bot integrationId: 5f11a650e4e987667c2051d1 integrationType: custom error: code: switchboard_invalid_target message: Switchboard invalid target switchboardReleaseControlEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: switchboard:releaseControl payload: conversation: id: f52b01137aa6c250bc7251fa type: personal userMergeEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: user:merge payload: mergedUsers: surviving: id: 26508c10541a4b0ff472e5e2 externalId: '912382197' authenticated: true discarded: id: 1a64f7f75028fef55f815007 externalId: '912382198' authenticated: true reason: api userUpdateEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 5f74a0d52b5315fc007e798a createdAt: '2020-09-30T15:14:29.834Z' type: user:update payload: user: id: 26508c10541a4b0ff472e5e2 externalId: 9128asd219s7 authenticated: true reason: authentication source: type: web integrationId: 5ecff63ffc3ab25f4561c8a0 userRemoveEvent: value: app: id: 5ebee0975ac5304b664a12fa webhook: id: 5f4eaef81e3dcc117c7ba48a version: v2 events: - id: 6748e3b2e176d554adbc1a4f createdAt: '2024-11-28T21:42:10.691Z' type: user:remove payload: user: id: 6748e3ae32378e732938e031 externalId: abc123 authenticated: true x-zendesk-owner: name: SunCo Engine channel: '#sunco-engine' x-zoas-lint-defaults: disable: - core/snake-case-parameter-names-not-in-header - core/snake-case-schema-properties - core/snake-case-path-keys x-tagGroups: - name: Account Provisioning tags: - Apps - App Keys - name: Attachments tags: - Attachments - name: Conversations tags: - Conversations - Participants - Messages - Activities - Switchboard Actions - name: Integrations tags: - Integrations - Webhooks - CustomIntegrationApiKeys - name: Switchboards tags: - Switchboards - Switchboard Integrations - name: Users tags: - Users - Clients - Devices - name: OAuth tags: - OAuth Endpoints - name: Changelog tags: - Changelog