sunshine-conversations-client 17.0.1
Sunshine Conversations API
Keywords: OpenAPI, OpenAPI-Generator, Sunshine Conversations API

    # Introduction  &lt;aside class&#x3D;\&quot;notice\&quot;&gt;&lt;strong&gt;Note:&lt;/strong&gt; The documentation below applies to v2 of the API. For users wanting to access v1, please proceed &lt;a href&#x3D;\&quot;https://docs.smooch.io/rest/v1\&quot;&gt;here&lt;/a&gt; instead. &lt;/aside&gt;  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 &#x60;content-type: application/json&#x60; 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:  &#x60;&#x60;&#x60; https://{subdomain}.zendesk.com/sc &#x60;&#x60;&#x60;  For legacy Sunshine Conversations customers, see [regions](https://docs.smooch.io/guide/regions/) for the list of supported base URLs.  &lt;aside class&#x3D;\&quot;notice\&quot;&gt;&lt;strong&gt;Note:&lt;/strong&gt; When configuring an API host, make sure to always use &lt;code&gt;https&lt;/code&gt;. Some API clients can have unexpected behaviour when following redirects from &lt;code&gt;http&lt;/code&gt; to &lt;code&gt;https&lt;/code&gt;.&lt;/aside&gt;  ## Errors  Sunshine Conversations uses standard HTTP status codes to communicate errors. In general, a &#x60;2xx&#x60; status code indicates success while &#x60;4xx&#x60; indicates an error, in which case, the response body includes a JSON object which includes an array of errors, with a text &#x60;code&#x60; and &#x60;title&#x60; containing more details. Multiple errors can only be included in a &#x60;400 Bad Request&#x60;. A &#x60;5xx&#x60; status code indicates that something went wrong on our end.  &#x60;&#x60;&#x60;javascript {    \&quot;errors\&quot;:  [     {         \&quot;code\&quot;: \&quot;unauthorized\&quot;,         \&quot;title\&quot;: \&quot;Authorization is required\&quot;     }    ] } &#x60;&#x60;&#x60;  ## 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 &#x60;page[after]&#x60; or &#x60;page[before]&#x60; query string parameter may be provided, they are cursors pointing to a record id.  The &#x60;page[after]&#x60; cursor indicates that only records **subsequent** to it should be returned.  The &#x60;page[before]&#x60; cursor indicates that only records **preceding** it should be returned.  **Only one** of &#x60;page[after]&#x60; or &#x60;page[before]&#x60; may be provided in a query, not both.  In most endpoints, an optional &#x60;page[size]&#x60; 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  &lt;a style&#x3D;\&quot;display:inline-block;background:url(https://run.pstmn.io/button.svg);height:30px;width: 123px;\&quot; href&#x3D;\&quot;https://docs.smooch.io/sunco-openapi/postman_collection.json\&quot;&gt;&lt;/a&gt;  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 &#x60;429 Too Many Requests&#x60; 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 &#x60;429&#x60; retry logic using exponential backoff and jitter.  ## Conversation Size Limits  Conversations are limited to 30,000 messages. Once you reach this maximum, a &#x60;423 Locked&#x60; 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: &#x60;integration&#x60;, &#x60;app&#x60;, and &#x60;account&#x60;.  | 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 |  &lt;aside class&#x3D;\&quot;notice\&quot;&gt;&lt;strong&gt;Note:&lt;/strong&gt; An additional scope of &lt;code&gt;user&lt;/code&gt; is used for &lt;a href&#x3D;\&quot;https://developer.zendesk.com/documentation/conversations/messaging-platform/users/authenticating-users/\&quot;&gt;authenticating users&lt;/a&gt; on the Zendesk Messaging SDKs. This scope, however, cannot be used with the v2 API.&lt;/aside&gt;  ## 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 &#x60;authorization&#x60; header. The token should be prefixed with “Bearer” followed by a space. For example: &#x60;Bearer your-jwt&#x60;. 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 &#x60;kid&#x60; 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.  &#x60;&#x60;&#x60;javascript {     \&quot;alg\&quot;: \&quot;HS256\&quot;,     \&quot;typ\&quot;: \&quot;JWT\&quot;,     \&quot;kid\&quot;: \&quot;act_5963ceb97cde542d000dbdb1\&quot; } &#x60;&#x60;&#x60;  #### 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*).  &#x60;&#x60;&#x60;javascript {     \&quot;scope\&quot;: \&quot;account\&quot; } &#x60;&#x60;&#x60;  - app-scoped JWTs can be generated with an API key associated with an app (app\_).  &#x60;&#x60;&#x60;javascript {    \&quot;scope\&quot;: \&quot;app\&quot; } &#x60;&#x60;&#x60;