Skip to content
Go to file


Failed to load latest commit information.


The Python package for the Smooch API.

The Smooch API is a unified interface for powering messaging in your customer experiences across every channel. Our API speeds access to new markets, reduces time to ship, eliminates complexity, and helps you build the best experiences for your customers. For more information, visit our official documentation.

This SDK is automatically generated by the Swagger Codegen project using the Smooch api spec.


Python 2.7 or 3.4+

Smooch API Version

The Smooch API offers multiple versions. Each release of this project targets one and only one Smooch API version. If you depend on an older version of the Smooch API, you may need to use an older release of this library. Use the table below as your guide:

Smooch API version smooch-python version to use
v1.1 Upgrade guide 4.0.0 or newer
v1 3.* or older


pip install smooch

(you may need to run pip with root permission: sudo pip install smooch)

Getting Started

Familiarity with Smooch API authentication is recommended.

Basic Authentication (recommended)

With basic authentication, you can use your API key ID and secret to authenticate API requests. See below for a code sample.

Authentication with JSON Web Tokens (JWTs)

See the JSON Web Tokens (JWTs) guide for more information and guidelines on when to use this method. In general, you'll want to favor using basic authentication.

To generate a JWT, use your API key ID and secret.

Using the pyjwt module:

import jwt
token_bytes = jwt.encode({'scope': 'app'},
                         headers={'kid': 'KEY_ID'})
token = token_bytes.decode('utf-8')

Running the code

import smooch
from import ApiException
from pprint import pprint

# Configure HTTP basic authorization: basicAuth
smooch.configuration.username = 'API_KEY_ID'
smooch.configuration.password = 'API_KEY_SECRET'

# OR

# Configure JWT authorization (alternative method): jwt
smooch.configuration.api_key['Authorization'] = 'YOUR_JWT'
smooch.configuration.api_key_prefix['Authorization'] = 'Bearer'

# create an instance of the API class
api_instance = smooch.AppApi()
app_create_body = smooch.AppCreate() # AppCreate | Body for a createApp request.

    api_response = api_instance.create_app(app_create_body)
except ApiException as e:
    print("Exception when calling AppApi->create_app: %s\n" % e)


Smooch is available in the following regions. The US region will be used by default. To target any other region, specify the region API host in For example: = ''

Documentation for API Endpoints

All URIs are relative to

Class Method HTTP request Description
AppApi create_app POST /v1.1/apps
AppApi create_secret_key POST /v1.1/apps/{appId}/keys
AppApi delete_app DELETE /v1.1/apps/{appId}
AppApi delete_secret_key DELETE /v1.1/apps/{appId}/keys/{keyId}
AppApi get_app GET /v1.1/apps/{appId}
AppApi get_app_jwt GET /v1.1/apps/{appId}/keys/{keyId}/jwt
AppApi get_sdk_ids GET /v1.1/apps/{appId}/sdks
AppApi get_secret_key GET /v1.1/apps/{appId}/keys/{keyId}
AppApi list_apps GET /v1.1/apps
AppApi list_secret_keys GET /v1.1/apps/{appId}/keys
AppApi update_app PUT /v1.1/apps/{appId}
AppUserApi delete_app_user DELETE /v1.1/apps/{appId}/appusers/{userId}
AppUserApi delete_app_user_profile DELETE /v1.1/apps/{appId}/appusers/{userId}/profile
AppUserApi get_app_user GET /v1.1/apps/{appId}/appusers/{userId}
AppUserApi get_app_user_auth_code GET /v1.1/apps/{appId}/appusers/{userId}/authcode
AppUserApi get_app_user_business_system_ids GET /v1.1/apps/{appId}/appusers/{userId}/businesssystems
AppUserApi get_app_user_entity_ids GET /v1.1/apps/{appId}/appusers/{userId}/channels
AppUserApi get_link_requests GET /v1.1/apps/{appId}/appusers/{userId}/linkrequest
AppUserApi link_app_user POST /v1.1/apps/{appId}/appusers/{userId}/channels
AppUserApi merge_users POST /v1.1/apps/{appId}/appusers/merge
AppUserApi post_image_message POST /v1.1/apps/{appId}/appusers/{userId}/images
AppUserApi pre_create_app_user POST /v1.1/apps/{appId}/appusers
AppUserApi unlink_app_user DELETE /v1.1/apps/{appId}/appusers/{userId}/channels/{channel}
AppUserApi update_app_user PUT /v1.1/apps/{appId}/appusers/{userId}
AttachmentsApi remove_attachment POST /v1.1/apps/{appId}/attachments/remove
AttachmentsApi upload_attachment POST /v1.1/apps/{appId}/attachments
ConversationApi conversation_activity POST /v1.1/apps/{appId}/appusers/{userId}/conversation/activity
ConversationApi delete_message DELETE /v1.1/apps/{appId}/appusers/{userId}/messages/{messageId}
ConversationApi delete_messages DELETE /v1.1/apps/{appId}/appusers/{userId}/messages
ConversationApi get_messages GET /v1.1/apps/{appId}/appusers/{userId}/messages
ConversationApi post_message POST /v1.1/apps/{appId}/appusers/{userId}/messages
ConversationApi reset_unread_count POST /v1.1/apps/{appId}/appusers/{userId}/conversation/read
DeploymentApi activate_phone_number POST /v1.1/whatsapp/deployments/{deploymentId}/activate
DeploymentApi confirm_code POST /v1.1/whatsapp/deployments/{deploymentId}/code/confirm
DeploymentApi create_deployment POST /v1.1/whatsapp/deployments
DeploymentApi delete_deployment DELETE /v1.1/whatsapp/deployments/{deploymentId}
DeploymentApi get_deployment GET /v1.1/whatsapp/deployments/{deploymentId}
DeploymentApi list_deployments GET /v1.1/whatsapp/deployments
IntegrationApi create_integration POST /v1.1/apps/{appId}/integrations
IntegrationApi create_integration_menu POST /v1.1/apps/{appId}/integrations/{integrationId}/menu
IntegrationApi delete_integration DELETE /v1.1/apps/{appId}/integrations/{integrationId}
IntegrationApi delete_integration_menu DELETE /v1.1/apps/{appId}/integrations/{integrationId}/menu
IntegrationApi get_integration GET /v1.1/apps/{appId}/integrations/{integrationId}
IntegrationApi get_integration_menu GET /v1.1/apps/{appId}/integrations/{integrationId}/menu
IntegrationApi get_integration_profile GET /v1.1/apps/{appId}/integrations/{integrationId}/profile
IntegrationApi list_integrations GET /v1.1/apps/{appId}/integrations
IntegrationApi update_integration PUT /v1.1/apps/{appId}/integrations/{integrationId}
IntegrationApi update_integration_menu PUT /v1.1/apps/{appId}/integrations/{integrationId}/menu
IntegrationApi update_integration_profile PUT /v1.1/apps/{appId}/integrations/{integrationId}/profile
IntegrationApi upload_integration_profile_photo PUT /v1.1/apps/{appId}/integrations/{integrationId}/profile/photo
MenuApi delete_menu DELETE /v1.1/apps/{appId}/menu
MenuApi get_menu GET /v1.1/apps/{appId}/menu
MenuApi update_menu PUT /v1.1/apps/{appId}/menu
NotificationApi post_notification POST /v1/apps/{appId}/notifications
ServiceAccountApi create_secret_key POST /v1.1/serviceaccounts/{serviceAccountId}/keys
ServiceAccountApi create_service_account POST /v1.1/serviceaccounts
ServiceAccountApi delete_secret_key DELETE /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}
ServiceAccountApi delete_service_account DELETE /v1.1/serviceaccounts/{serviceAccountId}
ServiceAccountApi get_jwt GET /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}/jwt
ServiceAccountApi get_secret_key GET /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}
ServiceAccountApi get_service_account GET /v1.1/serviceaccounts/{serviceAccountId}
ServiceAccountApi list_secret_keys GET /v1.1/serviceaccounts/{serviceAccountId}/keys
ServiceAccountApi list_service_accounts GET /v1.1/serviceaccounts
ServiceAccountApi update_service_account PUT /v1.1/serviceaccounts/{serviceAccountId}
TemplateApi create_template POST /v1.1/apps/{appId}/templates
TemplateApi delete_template DELETE /v1.1/apps/{appId}/templates/{templateId}
TemplateApi get_template GET /v1.1/apps/{appId}/templates/{templateId}
TemplateApi list_templates GET /v1.1/apps/{appId}/templates
TemplateApi update_template PUT /v1.1/apps/{appId}/templates/{templateId}
WebhookApi create_webhook POST /v1.1/apps/{appId}/webhooks
WebhookApi delete_webhook DELETE /v1.1/apps/{appId}/webhooks/{webhookId}
WebhookApi get_webhook GET /v1.1/apps/{appId}/webhooks/{webhookId}
WebhookApi list_webhooks GET /v1.1/apps/{appId}/webhooks
WebhookApi update_webhook PUT /v1.1/apps/{appId}/webhooks/{webhookId}

Documentation For Models

Documentation For Authorization


  • Type: HTTP basic authentication


  • Type: API key
  • API key parameter name: Authorization
  • Location: HTTP header

Integration with Google Cloud Platform

Swagger client is using urllib3 as default http library, however Google Cloud Platform disallows it. There are two ways you can use urllib3 in Appengine Standard: patch it to use App Engine’s URLFetch or enable sockets. Which one to use depends on your situation and needs. URLFetch is more cost-effective as long as your usage is within the limitations for free app. Sockets are only available for paid apps.

The first solution:

import smooch
from urllib3.contrib.appengine import AppEngineManager

# create swagger client
client = smooch.AppApi()
# patch urllib3 for App Engine to use URLFetch
client.api_client.rest_client.pool_manager = AppEngineManager()

You can skip this solution if you choose to go with sockets. Just add the following lines to the app.yaml.


Copyright and license

Copyright 2018 Zendesk, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You can’t perform that action at this time.