Package: python-intercom
Python bindings for the Intercom API (https://api.intercom.io).API Documentation.Package
Documentation.Upgrading informationVersion 3 of python-intercom isnot backwards compatiblewith
previous versions.Version 3 moves away from a global setup approach to the use of an
Intercom Client.Installationpip install python-intercomBasic UsageConfigure your clientfromintercom.clientimportClientintercom=Client(personal_access_token='my_personal_access_token')Note that certain resources will require an extended scope access token :Setting up Personal Access TokensResourcesResources 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/bulkExamplesUsers# 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():...# Bulk operations.# Submit bulk job, to create users, if any of the items in create_items match an existing user that user will be updatedintercom.users.submit_bulk_job(create_items=[{'user_id':25,'email':'alice@example.com'},{'user_id':25,'email':'bob@example.com'}])# Submit bulk job, to delete usersintercom.users.submit_bulk_job(delete_items=[{'user_id':25,'email':'alice@example.com'},{'user_id':25,'email':'bob@example.com'}])# Submit bulk job, to add items to existing jobintercom.users.submit_bulk_job(create_items=[{'user_id':25,'email':'alice@example.com'}],delete_items=[{'user_id':25,'email':'bob@example.com'}],'job_id':'job_abcd1234')Admins# Iterate over all adminsforadmininintercom.admins.all():...Companies# 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)Tags# Tag userstag=intercom.tags.tag_users(name='blue',users=[{'email':'test1@example.com'}])# Untag usersintercom.tags.untag_users(name='blue',users=[{'user_id':'42ea2f1b93891f6a99000427'}])# Iterate over all tagsfortaginintercom.tags.all():...# Tag companiestag=intercom.tags.tag(name='blue',companies=[{'id':'42ea2f1b93891f6a99000427'}])Segments# Find a segmentsegment=intercom.segments.find(id=segment_id)# Iterate over all segmentsforsegmentinintercom.segments.all():...Notes# 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'):...Conversations# 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)Full loading of an embedded entity# Given a conversation with a partial user, load the full user. This can be# done for any entityintercom.users.load(conversation.user)Sending messages# 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'})Eventsintercom.events.create(event_name='invited-friend',created_at=time.mktime(),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 behalfintercom.events.create(event_name="placed-order",email=current_user.email,created_at=1403001013metadata={'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 eventsintercom.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':'pi@example.org','invite_code':'ADDAFRIEND'}}])# Submit bulk job, to add items to existing jobintercom.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':'pi@example.org','invite_code':'ADDAFRIEND'}}],job_id='job_abcd1234')ContactsContacts represent logged out users of your application.# Create a contactcontact=intercom.contacts.create(email="some_contact@example.com")# Update a contactcontact.custom_attributes['foo']='bar'intercom.contacts.save(contact)# Find contacts by emailcontacts=intercom.contacts.find_all(email="some_contact@example.com")# Convert a contact into a userintercom.contacts.convert(contact,user)# Delete a contactintercom.contacts.delete(contact)Counts# App-wide countsintercom.counts.for_app()# Users in segment countsintercom.counts.for_type(type='user',count='segment')SubscriptionsSubscribe 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():...Bulk jobs# fetch a jobintercom.jobs.find(id='job_abcd1234')# fetch a job's error feedintercom.jobs.errors(id='job_abcd1234')ErrorsYou 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 ofintercom.Errorwill be raised. If desired, you can get
at the http_code of anErrorvia it’shttp_codemethod.The list of different error subclasses are listed below. As they all
inherit offIntercomErroryou can choose to exceptIntercomErroror the more specific error subclass:AuthenticationErrorServerErrorServiceUnavailableErrorServiceConnectionErrorResourceNotFoundBadGatewayErrorBadRequestErrorRateLimitExceededMultipleMatchingUsersErrorHttpErrorUnexpectedErrorRate LimitingCalling your clientsrate_limit_detailsreturns 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 TestsUnit tests:noseteststests/unitIntegration tests:INTERCOM_PERSONAL_ACCESS_TOKEN=xxxnoseteststests/integration