Please note that this is NOT an official Intercom SDK. The third party that maintained it reached out to us to note that they were unable to host it any longer. As it was being used by some Intercom customers we offered to host it to allow the current Python community to continue to use it. However, it will not be maintained or updated by Intercom. It is a community maintained SDK. Please see here for the official list of Intercom SDKs
Python bindings for the Intercom API (https://developers.intercom.com/intercom-api-reference).
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.
pip install python-intercom
fromintercom.clientimportClientintercom=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 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
# Find user by emailuser=intercom.users.find(email="bob@example.com")
# Find user by user_iduser=intercom.users.find(user_id="1")
# Find user by iduser=intercom.users.find(id="1")
# Create a useruser=intercom.users.create(email="bob@example.com", name="Bob Smith")
# Delete a useruser=intercom.users.find(id="1")
deleted_user=intercom.users.delete(user)
# Update custom_attributes for a useruser.custom_attributes["average_monthly_spend"] =1234.56intercom.users.save(user)
# Perform incrementinguser.increment('karma')
intercom.users.save(user)
# Iterate over all usersforuserinintercom.users.all():
...# Iterate over all adminsforadmininintercom.admins.all():
...# Add a user to one or more companiesuser=intercom.users.find(email='bob@example.com')
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 thisuser.companies= [
{
'id': 6,
'name': 'Intercom',
'custom_attributes': {
'referral_source': 'Google'
}
}
]
intercom.users.save(user)
# Find a company by company_idcompany=intercom.companies.find(company_id='44')
# Find a company by namecompany=intercom.companies.find(name='Some company')
# Find a company by idcompany=intercom.companies.find(id='41e66f0313708347cb0000d0')
# Update a companycompany.name='Updated company name'intercom.companies.save(company)
# Iterate over all companiesforcompanyinintercom.companies.all():
...
# Get a list of users in a companyintercom.companies.users(company.id)# Tag userstag=intercom.tags.tag(name='blue', users=[{'email': 'test1@example.com'}])
# Untag usersintercom.tags.untag(name='blue', users=[{'user_id': '42ea2f1b93891f6a99000427'}])
# Iterate over all tagsfortaginintercom.tags.all():
...
# Tag companiestag=intercom.tags.tag(name='blue', companies=[{'id': '42ea2f1b93891f6a99000427'}])# Find a segmentsegment=intercom.segments.find(id=segment_id)
# Iterate over all segmentsforsegmentinintercom.segments.all():
...# Find a note by idnote=intercom.notes.find(id=note)
# Create a note for a usernote=intercom.notes.create(
body="<p>Text for the note</p>",
email='joe@example.com')
# Iterate over all notes for a user via their email addressfornoteinintercom.notes.find_all(email='joe@example.com'):
...
# Iterate over all notes for a user via their user_idfornoteinintercom.notes.find_all(user_id='123'):
...# FINDING CONVERSATIONS FOR AN ADMIN# Iterate over all conversations (open and closed) assigned to an adminforconvoinintercom.conversations.find_all(type='admin', id='7'):
...
# Iterate over all open conversations assigned to an adminforconvoinintercom.conversations.find_all(type='admin', id=7, open=True):
...
# Iterate over closed conversations assigned to an adminforconvointercom.conversations.find_all(type='admin', id=7, open=False):
...
# Iterate over closed conversations for assigned an admin, before a certain# moment in timeforconvoinintercom.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 emailforconvoinintercom.onversations.find_all(email='joe@example.com',type='user'):
...
# Iterate over through all conversations (read + unread) with a user based on# the users emailforconvoinintercom.conversations.find_all(
email='joe@example.com', type='user', unread=False):
...
# Iterate over all unread conversations with a user based on the users emailforconvoinintercom.conversations.find_all(
email='joe@example.com', type='user', unread=true):
...
# FINDING A SINGLE CONVERSATIONconversation=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 partconversation.conversation_parts[0].part_type# Get the body of the second partconversation.conversation_parts[1].body# REPLYING TO CONVERSATIONS# User (identified by email) replies with a commentintercom.conversations.reply(
type='user', email='joe@example.com',
message_type='comment', body='foo')
# Admin (identified by email) replies with a commentintercom.conversations.reply(
type='admin', email='bob@example.com',
message_type='comment', body='bar')
# User (identified by email) replies with a comment and attachmentintercom.conversations.reply(id=conversation.id, type='user', email='joe@example.com', message_type='comment', body='foo', attachment_urls=['http://www.example.com/attachment.jpg'])
# Openintercom.conversations.open(id=conversation.id, admin_id='123')
# Closeintercom.conversations.close(id=conversation.id, admin_id='123')
# Assignintercom.conversations.assign(id=conversation.id, admin_id='123', assignee_id='124')
# Reply and Openintercom.conversations.reply(id=conversation.id, type='admin', admin_id='123', message_type='open', body='bar')
# Reply and Closeintercom.conversations.reply(id=conversation.id, type='admin', admin_id='123', message_type='close', body='bar')
# ASSIGNING CONVERSATIONS TO ADMINSintercom.conversations.reply(id=conversation.id, type='admin', assignee_id=assignee_admin.id, admin_id=admin.id, message_type='assignment')
# MARKING A CONVERSATION AS READintercom.conversations.mark_read(conversation.id)# Given a conversation with a partial user, load the full user. This can be# done for any entityintercom.users.load(conversation.user)# InApp message from admin to userintercom.messages.create(**{
"message_type": "inapp",
"body": "What's up :)",
"from": {
"type": "admin",
"id": "1234"
},
"to": {
"type": "user",
"id": "5678"
}
})
# Email message from admin to userintercom.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 userintercom.messages.create(**{
"from": {
"type": "user",
"id": "536e564f316c83104c000020"
},
"body": "halp"
})
# Message from admin to contactintercom.messages.create(**{
'body': 'How can I help :)',
'from': {
'type': 'admin',
'id': '1234'
},
'to': {
'type': 'contact',
'id': '536e5643as316c83104c400671'
}
})
# Message from a contactintercom.messages.create(**{
'from'=> {
'type': 'contact',
'id': '536e5643as316c83104c400671'
},
'body': 'halp'
})importtimeintercom.events.create(
event_name='invited-friend',
created_at=int(time.mktime(time.localtime())),
email=user.email,
metadata={
'invitee_email': 'pi@example.org',
'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
current_user=intercom.users.find(id="1")
intercom.events.create(
event_name="placed-order",
email=current_user.email,
created_at=1403001013,
metadata={
'order_date': time.mktime(time.localtime()),
'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)
Contacts represent logged out users of your application.
# Create a contactcontact=intercom.leads.create(email="some_contact@example.com")
# Update a contactcontact.custom_attributes['foo'] ='bar'intercom.leads.save(contact)
# Find contacts by emailcontacts=intercom.leads.find_all(email="some_contact@example.com")
# Merge a contact into a useruser=intercom.users.find(id="1")
intercom.leads.convert(contact, user)
# Delete a contactintercom.leads.delete(contact)# App-wide countsintercom.counts.for_app()
# Users in segment countsintercom.counts.for_type(type='user', count='segment')Subscribe to events in Intercom to receive webhooks.
# create a subscriptionintercom.subscriptions.create(url='http://example.com', topics=['user.created'])
# fetch a subscriptionintercom.subscriptions.find(id='nsub_123456789')
# list subscriptionsintercom.subscriptions.all():
...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:
AuthenticationErrorServerErrorServiceUnavailableErrorServiceConnectionErrorResourceNotFoundBadGatewayErrorBadRequestErrorRateLimitExceededMultipleMatchingUsersErrorHttpErrorUnexpectedErrorCalling 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)}Unit tests:
nosetests tests/unitIntegration tests:
INTERCOM_PERSONAL_ACCESS_TOKEN=xxx nosetests tests/integration