python-intercom 3.1.0

Intercom API wrapper

Python bindings for the Intercom API (https://api.intercom.io).

API Documentation.

Package Documentation.

Upgrading information

Version 3 of python-intercom is not backwards compatible with previous versions.

Version 3 moves away from a global setup approach to the use of an Intercom Client.

Installation

pip install python-intercom

Basic Usage

Configure your client

from intercom.client import Client
intercom = Client(personal_access_token='my_personal_access_token')

Note that certain resources will require an extended scope access token : Setting up Personal Access Tokens

Resources

Resources this API supports:

https://api.intercom.io/users
https://api.intercom.io/contacts
https://api.intercom.io/companies
https://api.intercom.io/counts
https://api.intercom.io/tags
https://api.intercom.io/notes
https://api.intercom.io/segments
https://api.intercom.io/events
https://api.intercom.io/conversations
https://api.intercom.io/messages
https://api.intercom.io/subscriptions
https://api.intercom.io/jobs
https://api.intercom.io/bulk

Examples

Users

# Find user by email
user = intercom.users.find(email="[e-mail]")
# Find user by user_id
user = intercom.users.find(user_id="1")
# Find user by id
user = intercom.users.find(id="1")
# Create a user
user = intercom.users.create(email="[e-mail]", name="Bob Smith")
# Delete a user
user = intercom.users.find(id="1")
deleted_user = intercom.users.delete(user)
# Update custom_attributes for a user
user.custom_attributes["average_monthly_spend"] = 1234.56
intercom.users.save(user)
# Perform incrementing
user.increment('karma')
intercom.users.save(user)
# Iterate over all users
for user in intercom.users.all():
    ...

# Bulk operations.
# Submit bulk job, to create users, if any of the items in create_items match an existing user that user will be updated
intercom.users.submit_bulk_job(create_items=[{'user_id': 25, 'email': '[e-mail]'}, {'user_id': 25, 'email': '[e-mail]'}])
# Submit bulk job, to delete users
intercom.users.submit_bulk_job(delete_items=[{'user_id': 25, 'email': '[e-mail]'}, {'user_id': 25, 'email': '[e-mail]'}])
# Submit bulk job, to add items to existing job
intercom.users.submit_bulk_job(create_items=[{'user_id': 25, 'email': '[e-mail]'}], delete_items=[{'user_id': 25, 'email': '[e-mail]'}], 'job_id': 'job_abcd1234')

Admins

# Iterate over all admins
for admin in intercom.admins.all():
    ...

Companies

# Add a user to one or more companies
user = intercom.users.find(email='[e-mail]')
user.companies = [
    {'company_id': 6, 'name': 'Intercom'},
    {'company_id': 9, 'name': 'Test Company'}
]
intercom.users.save(user)
# You can also pass custom attributes within a company as you do this
user.companies = [
    {
        'id': 6,
        'name': 'Intercom',
        'custom_attributes': {
            'referral_source': 'Google'
        }
    }
]
intercom.users.save(user)
# Find a company by company_id
company = intercom.companies.find(company_id='44')
# Find a company by name
company = intercom.companies.find(name='Some company')
# Find a company by id
company = intercom.companies.find(id='41e66f0313708347cb0000d0')
# Update a company
company.name = 'Updated company name'
intercom.companies.save(company)
# Iterate over all companies
for company in intercom.companies.all():
    ...
# Get a list of users in a company
intercom.companies.users(company.id)

Tags

# Tag users
tag = intercom.tags.tag_users(name='blue', users=[{'email': '[e-mail]'}])
# Untag users
intercom.tags.untag_users(name='blue', users=[{'user_id': '42ea2f1b93891f6a99000427'}])
# Iterate over all tags
for tag in intercom.tags.all():
    ...
# Tag companies
tag = intercom.tags.tag(name='blue', companies=[{'id': '42ea2f1b93891f6a99000427'}])

Segments

# Find a segment
segment = intercom.segments.find(id=segment_id)
# Iterate over all segments
for segment in intercom.segments.all():
    ...

Notes

# Find a note by id
note = intercom.notes.find(id=note)
# Create a note for a user
note = intercom.notes.create(
    body="<p>Text for the note</p>",
    email='[e-mail]')
# Iterate over all notes for a user via their email address
for note in intercom.notes.find_all(email='[e-mail]'):
    ...
# Iterate over all notes for a user via their user_id
for note in intercom.notes.find_all(user_id='123'):
    ...

Conversations

# FINDING CONVERSATIONS FOR AN ADMIN
# Iterate over all conversations (open and closed) assigned to an admin
for convo in intercom.conversations.find_all(type='admin', id='7'):
    ...
# Iterate over all open conversations assigned to an admin
for convo in intercom.conversations.find_all(type='admin', id=7, open=True):
    ...
# Iterate over closed conversations assigned to an admin
for convo intercom.conversations.find_all(type='admin', id=7, open=False):
    ...
# Iterate over closed conversations for assigned an admin, before a certain
# moment in time
for convo in intercom.conversations.find_all(
        type='admin', id= 7, open= False, before=1374844930):
    ...

# FINDING CONVERSATIONS FOR A USER
# Iterate over all conversations (read + unread, correct) with a user based on
# the users email
for convo in intercom.onversations.find_all(email='[e-mail]',type='user'):
    ...
# Iterate over through all conversations (read + unread) with a user based on
# the users email
for convo in intercom.conversations.find_all(
        email='[e-mail]', type='user', unread=False):
    ...
# Iterate over all unread conversations with a user based on the users email
for convo in intercom.conversations.find_all(
        email='[e-mail]', type='user', unread=true):
    ...

# FINDING A SINGLE CONVERSATION
conversation = intercom.conversations.find(id='1')

# INTERACTING WITH THE PARTS OF A CONVERSATION
# Getting the subject of a part (only applies to email-based conversations)
conversation.rendered_message.subject
# Get the part_type of the first part
conversation.conversation_parts[0].part_type
# Get the body of the second part
conversation.conversation_parts[1].body

# REPLYING TO CONVERSATIONS
# User (identified by email) replies with a comment
intercom.conversations.reply(
    type='user', email='[e-mail]',
    message_type='comment', body='foo')
# Admin (identified by email) replies with a comment
intercom.conversations.reply(
    type='admin', email='[e-mail]',
    message_type='comment', body='bar')
# User (identified by email) replies with a comment and attachment
intercom.conversations.reply(id=conversation.id, type='user', email='[e-mail]', message_type='comment', body='foo', attachment_urls=['http://www.example.com/attachment.jpg'])

# Open
intercom.conversations.open(id=conversation.id, admin_id='123')

# Close
intercom.conversations.close(id=conversation.id, admin_id='123')

# Assign
intercom.conversations.assign(id=conversation.id, admin_id='123', assignee_id='124')

# Reply and Open
intercom.conversations.reply(id=conversation.id, type='admin', admin_id='123', message_type='open', body='bar')

# Reply and Close
intercom.conversations.reply(id=conversation.id, type='admin', admin_id='123', message_type='close', body='bar')

# ASSIGNING CONVERSATIONS TO ADMINS
intercom.conversations.reply(id=conversation.id, type='admin', assignee_id=assignee_admin.id, admin_id=admin.id, message_type='assignment')

# MARKING A CONVERSATION AS READ
intercom.conversations.mark_read(conversation.id)

Full loading of an embedded entity

# Given a conversation with a partial user, load the full user. This can be
# done for any entity
intercom.users.load(conversation.user)

Sending messages

# InApp message from admin to user
intercom.messages.create(**{
    "message_type": "inapp",
    "body": "What's up :)",
    "from": {
        "type": "admin",
        "id": "1234"
    },
    "to": {
        "type": "user",
        "id": "5678"
    }
})

# Email message from admin to user
intercom.messages.create(**{
    "message_type": "email",
    "subject": "Hey there",
    "body": "What's up :)",
    "template": "plain", # or "personal",
    "from": {
        "type": "admin",
        "id": "1234"
    },
    "to": {
        "type": "user",
        "id": "536e564f316c83104c000020"
    }
})

# Message from a user
intercom.messages.create(**{
    "from": {
        "type": "user",
        "id": "536e564f316c83104c000020"
    },
    "body": "halp"
})

# Message from admin to contact
intercom.messages.create(**{
    'body': 'How can I help :)',
    'from': {
        'type': 'admin',
        'id': '1234'
    },
    'to': {
        'type': 'contact',
        'id': '536e5643as316c83104c400671'
    }
})

# Message from a contact
intercom.messages.create(**{
    'from' => {
        'type': 'contact',
        'id': '536e5643as316c83104c400671'
    },
    'body': 'halp'
})

Events

intercom.events.create(
    event_name='invited-friend',
    created_at=time.mktime(),
    email=user.email,
    metadata={
        'invitee_email': '[e-mail]',
        'invite_code': 'ADDAFRIEND',
        'found_date': 12909364407
    }
)

# Retrieve event list for user with id:'123abc'
intercom.events.find_all(type='user', "intercom_user_id"="123abc)

Metadata Objects support a few simple types that Intercom can present on your behalf

intercom.events.create(
    event_name="placed-order",
    email=current_user.email,
    created_at=1403001013
    metadata={
        'order_date': time.mktime(),
        'stripe_invoice': 'inv_3434343434',
        'order_number': {
            'value': '3434-3434',
            'url': 'https://example.org/orders/3434-3434'
        },
        'price': {
            'currency': 'usd',
            'amount': 2999
        }
    }
)

The metadata key values in the example are treated as follows-

• order_date: a Date (key ends with ‘_date’).

• stripe_invoice: The identifier of the Stripe invoice (has a ‘stripe_invoice’ key)

• order_number: a Rich Link (value contains ‘url’ and ‘value’ keys)

• price: An Amount in US Dollars (value contains ‘amount’ and ‘currency’ keys)

Bulk operations.

# Submit bulk job, to create events
intercom.events.submit_bulk_job(create_items: [
    {
        'event_name': 'ordered-item',
        'created_at': 1438944980,
        'user_id': '314159',
        'metadata': {
            'order_date': 1438944980,
            'stripe_invoice': 'inv_3434343434'
        }
    },
    {
        'event_name': 'invited-friend',
        'created_at': 1438944979,
        'user_id': '314159',
        'metadata': {
            'invitee_email': '[e-mail]',
            'invite_code': 'ADDAFRIEND'
        }
    }
])

# Submit bulk job, to add items to existing job
intercom.events.submit_bulk_job(create_items=[
    {
        'event_name': 'ordered-item',
        'created_at': 1438944980,
        'user_id': '314159',
        'metadata': {
            'order_date': 1438944980,
            'stripe_invoice': 'inv_3434343434'
        }
    },
    {
        'event_name': 'invited-friend',
        'created_at': 1438944979,
        'user_id': "314159",
        'metadata': {
            'invitee_email': '[e-mail]',
            'invite_code': 'ADDAFRIEND'
        }
    }
    ], job_id='job_abcd1234')

Contacts

Contacts represent logged out users of your application.

# Create a contact
contact = intercom.contacts.create(email="[e-mail]")

# Update a contact
contact.custom_attributes['foo'] = 'bar'
intercom.contacts.save(contact)

# Find contacts by email
contacts = intercom.contacts.find_all(email="[e-mail]")

# Convert a contact into a user
intercom.contacts.convert(contact, user)

# Delete a contact
intercom.contacts.delete(contact)

Counts

# App-wide counts
intercom.counts.for_app()

# Users in segment counts
intercom.counts.for_type(type='user', count='segment')

Subscriptions

Subscribe to events in Intercom to receive webhooks.

# create a subscription
intercom.subscriptions.create(url='http://example.com', topics=['user.created'])

# fetch a subscription
intercom.subscriptions.find(id='nsub_123456789')

# list subscriptions
intercom.subscriptions.all():
    ...

Bulk jobs

# fetch a job
intercom.jobs.find(id='job_abcd1234')

# fetch a job's error feed
intercom.jobs.errors(id='job_abcd1234')

Errors

You do not need to deal with the HTTP response from an API call directly. If there is an unsuccessful response then an error that is a subclass of intercom.Error will be raised. If desired, you can get at the http_code of an Error via it’s http_code method.

The list of different error subclasses are listed below. As they all inherit off IntercomError you can choose to except IntercomError or the more specific error subclass:

AuthenticationError
ServerError
ServiceUnavailableError
ServiceConnectionError
ResourceNotFound
BadGatewayError
BadRequestError
RateLimitExceeded
MultipleMatchingUsersError
HttpError
UnexpectedError

Rate Limiting

Calling your clients rate_limit_details returns a dict that contains details about your app’s current rate limit.

intercom.rate_limit_details
# {'limit': 180, 'remaining': 179, 'reset_at': datetime.datetime(2014, 10, 07, 14, 58)}

Running the Tests

Unit tests:

nosetests tests/unit

Integration tests:

INTERCOM_PERSONAL_ACCESS_TOKEN=xxx nosetests tests/integration