Skip to content

zendesk/sunshine-conversations-python

BranchesTags

Repository files navigation

sunshine-conversations-client

Introduction

Note: The documentation below applies to v2 of the API. For users wanting to access v1, please proceed here instead.

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 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.

{
   \"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.

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, with more languages to come. These helpful libraries wrap calls to the API and can make interfacing with Sunshine Conversations easier.

Postman Collection

<a style="display:inline-block;background:url(https://run.pstmn.io/button.svg);height:30px;width: 123px;" href="https://docs.smooch.io/sunco-openapi/postman_collection.json\">

In addition to API libraries, Sunshine Conversations also has a Postman collection that can be used for development or testing purposes. See the guide 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 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 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.

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 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.

Basic Authentication

API requests can be authenticated with basic 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 for more details.

JWTs

JSON Web Tokens (JWTs) are an industry standard authentication method. The full specification is described here, 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.

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.

{
    \"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*).
{
    \"scope\": \"account\"
}
  • app-scoped JWTs can be generated with an API key associated with an app (app\_).
{
   \"scope\": \"app\"
}

This Python package is automatically generated by the OpenAPI Generator project:

  • API version: 17.0.0
  • Package version: 17.0.1
  • Generator version: 7.12.0
  • Build package: org.openapitools.codegen.languages.PythonClientCodegen

Requirements.

Python 3.8+

Installation & Usage

pip install

If the python package is hosted on a repository, you can install directly using:

pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git)

Then import the package:

import sunshine_conversations_client

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import sunshine_conversations_client

Tests

Execute pytest to run the tests.

Getting Started

Please follow the installation procedure and then run the following:

import sunshine_conversations_client
from sunshine_conversations_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.smooch.io
# See configuration.py for a list of all supported configuration parameters.
configuration = sunshine_conversations_client.Configuration(
    host = "https://api.smooch.io"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure HTTP basic authorization: basicAuth
configuration = sunshine_conversations_client.Configuration(
    username = os.environ["USERNAME"],
    password = os.environ["PASSWORD"]
)

# Configure Bearer authorization (JWT): bearerAuth
configuration = sunshine_conversations_client.Configuration(
    access_token = os.environ["BEARER_TOKEN"]
)


# Enter a context with an instance of the API client
with sunshine_conversations_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = sunshine_conversations_client.ActivitiesApi(api_client)
    app_id = '5d8cff3cd55b040010928b5b' # str | Identifies the app.
    conversation_id = '029c31f25a21b47effd7be90' # str | Identifies the conversation.
    activity_post = {"author":{"type":"user","userId":"5963c0d619a30a2e00de36b8"},"type":"conversation:read"} # ActivityPost | 

    try:
        # Post Activity
        api_response = api_instance.post_activity(app_id, conversation_id, activity_post)
        print("The response of ActivitiesApi->post_activity:\n")
        pprint(api_response)
    except ApiException as e:
        print("Exception when calling ActivitiesApi->post_activity: %s\n" % e)

Documentation for API Endpoints

All URIs are relative to https://api.smooch.io

Class Method HTTP request Description
ActivitiesApi post_activity POST /v2/apps/{appId}/conversations/{conversationId}/activity Post Activity
AppKeysApi create_app_key POST /v2/apps/{appId}/keys Create App Key
AppKeysApi delete_app_key DELETE /v2/apps/{appId}/keys/{keyId} Delete App Key
AppKeysApi get_app_key GET /v2/apps/{appId}/keys/{keyId} Get App Key
AppKeysApi list_app_keys GET /v2/apps/{appId}/keys List App Keys
AppsApi create_app POST /v2/apps Create App
AppsApi delete_app DELETE /v2/apps/{appId} Delete App
AppsApi get_app GET /v2/apps/{appId} Get App
AppsApi list_apps GET /v2/apps List Apps
AppsApi update_app PATCH /v2/apps/{appId} Update App
AttachmentsApi delete_attachment POST /v2/apps/{appId}/attachments/remove Delete Attachment
AttachmentsApi upload_attachment POST /v2/apps/{appId}/attachments Upload Attachment
ClientsApi create_client POST /v2/apps/{appId}/users/{userIdOrExternalId}/clients Create Client
ClientsApi list_clients GET /v2/apps/{appId}/users/{userIdOrExternalId}/clients List Clients
ClientsApi remove_client DELETE /v2/apps/{appId}/users/{userIdOrExternalId}/clients/{clientId} Remove Client
ConversationsApi create_conversation POST /v2/apps/{appId}/conversations Create Conversation
ConversationsApi delete_conversation DELETE /v2/apps/{appId}/conversations/{conversationId} Delete Conversation
ConversationsApi download_message_ref POST /v2/apps/{appId}/conversations/{conversationId}/download Download Message Ref
ConversationsApi get_conversation GET /v2/apps/{appId}/conversations/{conversationId} Get Conversation
ConversationsApi list_conversations GET /v2/apps/{appId}/conversations List Conversations
ConversationsApi post_conversion_events POST /v2/apps/{appId}/conversations/{conversationId}/conversionEvents Post Conversion Events
ConversationsApi update_conversation PATCH /v2/apps/{appId}/conversations/{conversationId} Update Conversation
CustomIntegrationApiKeysApi create_custom_integration_key POST /v2/apps/{appId}/integrations/{integrationId}/keys Create Integration Key
CustomIntegrationApiKeysApi delete_custom_integration_key DELETE /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId} Delete Integration Key
CustomIntegrationApiKeysApi get_custom_integration_key GET /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId} Get Integration Key
CustomIntegrationApiKeysApi list_custom_integration_keys GET /v2/apps/{appId}/integrations/{integrationId}/keys List Integration Keys
DevicesApi get_device GET /v2/apps/{appId}/users/{userIdOrExternalId}/devices/{deviceId} Get Device
DevicesApi list_devices GET /v2/apps/{appId}/users/{userIdOrExternalId}/devices List Devices
IntegrationsApi create_integration POST /v2/apps/{appId}/integrations Create Integration
IntegrationsApi delete_integration DELETE /v2/apps/{appId}/integrations/{integrationId} Delete Integration
IntegrationsApi get_integration GET /v2/apps/{appId}/integrations/{integrationId} Get Integration
IntegrationsApi list_integrations GET /v2/apps/{appId}/integrations List Integrations
IntegrationsApi update_integration PATCH /v2/apps/{appId}/integrations/{integrationId} Update Integration
MessagesApi delete_all_messages DELETE /v2/apps/{appId}/conversations/{conversationId}/messages Delete All Messages
MessagesApi delete_message DELETE /v2/apps/{appId}/conversations/{conversationId}/messages/{messageId} Delete Message
MessagesApi list_messages GET /v2/apps/{appId}/conversations/{conversationId}/messages List Messages
MessagesApi post_message POST /v2/apps/{appId}/conversations/{conversationId}/messages Post Message
OAuthEndpointsApi authorize GET /oauth/authorize Authorize
OAuthEndpointsApi get_token POST /oauth/token Get Token
OAuthEndpointsApi get_token_info GET /v2/tokenInfo Get Token Info
OAuthEndpointsApi revoke_access DELETE /oauth/authorization Revoke Access
ParticipantsApi join_conversation POST /v2/apps/{appId}/conversations/{conversationId}/join Join Conversation
ParticipantsApi leave_conversation POST /v2/apps/{appId}/conversations/{conversationId}/leave Leave Conversation
ParticipantsApi list_participants GET /v2/apps/{appId}/conversations/{conversationId}/participants List Participants
SwitchboardActionsApi accept_control POST /v2/apps/{appId}/conversations/{conversationId}/acceptControl Accept Control
SwitchboardActionsApi offer_control POST /v2/apps/{appId}/conversations/{conversationId}/offerControl Offer Control
SwitchboardActionsApi pass_control POST /v2/apps/{appId}/conversations/{conversationId}/passControl Pass Control
SwitchboardActionsApi release_control POST /v2/apps/{appId}/conversations/{conversationId}/releaseControl Release Control
SwitchboardIntegrationsApi create_switchboard_integration POST /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations Create Switchboard Integration
SwitchboardIntegrationsApi delete_switchboard_integration DELETE /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId} Delete Switchboard Integration
SwitchboardIntegrationsApi list_switchboard_integrations GET /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations List Switchboard Integrations
SwitchboardIntegrationsApi update_switchboard_integration PATCH /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId} Update Switchboard Integration
SwitchboardsApi create_switchboard POST /v2/apps/{appId}/switchboards Create Switchboard
SwitchboardsApi delete_switchboard DELETE /v2/apps/{appId}/switchboards/{switchboardId} Delete Switchboard
SwitchboardsApi list_switchboards GET /v2/apps/{appId}/switchboards List Switchboards
SwitchboardsApi update_switchboard PATCH /v2/apps/{appId}/switchboards/{switchboardId} Update Switchboard
UsersApi create_user POST /v2/apps/{appId}/users Create User
UsersApi delete_user DELETE /v2/apps/{appId}/users/{userIdOrExternalId} Delete User
UsersApi delete_user_personal_information DELETE /v2/apps/{appId}/users/{userIdOrExternalId}/personalinformation Delete User Personal Information
UsersApi get_user GET /v2/apps/{appId}/users/{userIdOrExternalId} Get User
UsersApi sync_user POST /v2/apps/{appId}/users/{zendeskId}/sync Synchronize User
UsersApi update_user PATCH /v2/apps/{appId}/users/{userIdOrExternalId} Update User
WebhooksApi create_webhook POST /v2/apps/{appId}/integrations/{integrationId}/webhooks Create Webhook
WebhooksApi delete_webhook DELETE /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId} Delete Webhook
WebhooksApi get_webhook GET /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId} Get Webhook
WebhooksApi list_webhooks GET /v2/apps/{appId}/integrations/{integrationId}/webhooks List Webhooks
WebhooksApi update_webhook PATCH /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId} Update Webhook

Documentation For Models

Documentation For Authorization

Authentication schemes defined for the API:

bearerAuth

  • Type: Bearer authentication (JWT)

basicAuth

  • Type: HTTP basic authentication

Author

About

Smooch API Library for Python

Topics

smooch-lib

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

24 stars

Watchers

216 watching

Forks

10 forks
Report repository

Releases 6

5.29.0 Latest
Oct 6, 2020
+ 5 releases

Packages

No packages published

Contributors 6

Languages