Python library

You can use the Outbound Python library with your application to send user and event data to Zendesk Connect. You can also use it to manage device tokens if you have a mobile app and want to use push notifications.

The library currently only supports Python 2.7. If you use a later version of Python, another option is to use the Outbound REST API with an HTTP library like requests.

This document covers the following topics:

You can also examine the library's source code on Github.

Install the Outbound library

$ pip install outbound

Note: The library only supports Python 2.7.

Include the library in your project

import outbound

outbound.init("PRIVATE_KEY")

For more information on the private key, see Authentication in the introduction.

Identify a user

Use the outbound.identify() method to send user data to Connect. The method takes the following arguments, all of which are optional except the user id:

  • a string containing the user id
  • first_name - the user's first name
  • last_name - the user's last name
  • email - the user's email address
  • phone_number - a string containing the user's phone number
  • apns_tokens - an array of one or more iOS device token strings
  • gcm_tokens - an array of one or more Android device token strings
  • previous_id - a string containing an alternate user id
  • attributes - a dictionary of custom user attributes
  • on_error - a function to handle an identify request error
  • on_success - a function to handle an identify request success

For more information about the arguments, see Users. For more information about the callbacks, see Using callback functions.

Example
outbound.identify(
    '4512345',
    first_name='Jane',
    last_name='Doe',
    email='jdoe@example.com',
    phone_number='+1 555-123-4567',
    attributes=dict(
        membership_level='Gold',
    ),
    on_error=handle_identify_error,
    on_success=handle_identify_success
)

Track an event

Use the outbound.track() method to send event data to Connect. The method takes the following arguments:

outbound.track(
    'USER_ID',
    'EVENT_NAME',
    properties=dict(
        some_custom_property='Loren Ipsum'
    ),
    on_error=on_error_callback_func,
    on_success=on_success_callback_func
)

For more information about the arguments, see Events.

The track() method sends the data to Connect as soon as it runs, so make sure it has access to the user and event data.

Example
outbound.track(
    '4512345',
    'renewMembership',
    properties=dict(
        membership_valid=True,
        membership_renewalDate='2018-06-12'
    ),
    on_error=handle_track_error,
    on_success=handle_track_success
)

Provide a device token

If you have a mobile app and want to use push notifications in your Connect campaigns, you must provide the user's APNs (iOS) or GCM (Android) token to Connect. You can provide the token in one of two ways:

  • Send the user's token when you identify the user, using the apns_tokens or gcm_tokens arguments in the outbound.identify() method. See Identify a user above.

  • Use the outbound.register() method, which takes the following arguments:

    outbound.register_token(
        outbound.APNS,
        'USER_ID',
        'TOKEN',
        on_error=on_error_callback_function,
        on_success=on_success_callback_func,
    )
    

    The first argument must be either outbound.APNS or outbound.GCM.

Disable a device token

Use the outbound.disable_token() method if you no longer want to send notifications to the user's device. The method takes the following arguments:

outbound.disable_token(
    outbound.GCM,
    'USER_ID',
    'TOKEN',
    on_error=on_error_callback_function,
    on_success=on_success_callback_func
)

The first argument must be either outbound.APNS or outbound.GCM.

To enable the token again, specify it again in the identify() or register() method.

If you use register() and disable_token(), Connect recommends not sending any tokens in identify(). This lets you more easily control the state of your tokens.

Using callback functions

You can use the optional on_error and on_success method arguments to specify callback functions to run after the operation is complete.

  • the on_error callback function receives two parameters. The first is an integer corresponding to one of outbound.ERROR_XXXXX. See the source file on Github for the possible values. The second parameter is a string that either describes the error or, in the case of an error response from Connect, consists of the HTTP response body.

  • the on_success callback function receives no parameters.

Example
def send_event(user, event):
    outbound.track(
        user,
        event,
        on_error=report_error,
        on_success=report_success
    )

def report_error(code, msg):
    print code
    print msg

def report_success():
    print 'Event successfully sent'

send_event('4512345', 'renewMembership')