OpenAPI specification

OpenAPI is an industry standard technology used to specify the expected inputs and outputs of HTTP-based APIs. The OpenAPI definition for an API can be used as documentation of the API's capabilities. It can also be interpreted to automatically generate client libraries for invoking the API in many popular programming languages. Zendesk Messaging maintains and publishes a public version of our OpenAPI specification for integrators to use as a reference.

API specification

The latest version of the OpenAPI specification can be found on GitHub, published in YAML format. This specification is used directly to generate the hosted API reference, and is updated regularly.

The specification for the v1.1 API can also be found in the same GitHub repository, tagged as version 5.29. However, the v1.1 spec is no longer updated as of September 1st, 2020.

Generated API clients

API libraries

Zendesk provides API libraries for a few major programming languages which can be used to interact with the Sunshine Conversations v2 API. These wrapper libraries are automatically generated from the OpenAPI spec using the OpenAPI Generator open source project. The resulting generated code is open source on our GitHub, and also published on major package managers for supported each language. You can find a summary in the table below:

Language	Source code	Distribution
Java	sunshine-conversations-java	Installable via Maven or Gradle
JavaScript (Node.js)	sunshine-conversations-javascript	sunshine-conversations-client on NPM
Ruby	sunshine-conversations-ruby	sunshine-conversations-client gem
Python	sunshine-conversations-python	sunshine-conversations-client on pip

Postman collection

In addition to the generated wrapper libraries discussed above, the OpenAPI spec is also used to generate a Postman collection that can be used to easily test the API without writing any code. If you have Postman already installed or want to use Postman for Web, click the Run in Postman button below.

Note: To download the collection without directly importing it into Postman, the JSON file can be found here. This object can then be manually imported into Postman, if desired. We also have a collection for exercising the v1.1 API, found here.

Once imported, you will need to configure your Postman client with the proper credentials for calling the API. See Using the Conversations API keys for instructions on how to obtain your API key and app id, or API authentication for more details. Then, use Postman environment variables to configure the following values:

Variable	Value
url	https://{subdomain}.zendesk.com/sc
appId	app id obtained above
keyId	key id obtained above
secret	key secret obtained above
conversationId	id of the conversation you intend to access or modify