{"id":26091656,"url":"https://github.com/intercom/python-intercom","last_synced_at":"2025-04-06T14:10:26.652Z","repository":{"id":38051300,"uuid":"3619880","full_name":"intercom/python-intercom","owner":"intercom","description":"Python wrapper for the Intercom API.","archived":false,"fork":false,"pushed_at":"2024-07-30T15:10:17.000Z","size":1163,"stargazers_count":237,"open_issues_count":50,"forks_count":145,"subscribers_count":108,"default_branch":"master","last_synced_at":"2025-03-30T13:07:43.462Z","etag":null,"topics":["intercom","python"],"latest_commit_sha":null,"homepage":"https://keyes.ie/things/python-intercom/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intercom.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE.rst","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-03-04T17:57:53.000Z","updated_at":"2025-01-28T16:30:05.000Z","dependencies_parsed_at":"2024-06-18T15:23:09.670Z","dependency_job_id":"20ba5433-a73a-42cc-82f8-67db7e87cec1","html_url":"https://github.com/intercom/python-intercom","commit_stats":null,"previous_names":["jkeyes/python-intercom"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intercom%2Fpython-intercom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intercom%2Fpython-intercom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intercom%2Fpython-intercom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intercom%2Fpython-intercom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intercom","download_url":"https://codeload.github.com/intercom/python-intercom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247261450,"owners_count":20910092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["intercom","python"],"created_at":"2025-03-09T10:22:40.741Z","updated_at":"2025-04-06T14:10:26.625Z","avatar_url":"https://github.com/intercom.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"python-intercom\n===============\n\n|PyPI Version| |PyPI Downloads| |Travis CI Build| |Coverage Status|\n\nNot officially supported\n------------------------\nPlease 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. \nAs it was being used by some Intercom customers we offered to host it to allow the current Python community to continue to use it. \nHowever, it will not be maintained or updated by Intercom. It is a community maintained SDK.\nPlease see `here \u003chttps://developers.intercom.com/building-apps/docs/sdks-plugins\u003e`__ for the official list of Intercom SDKs\n\nPython bindings for the Intercom API (https://developers.intercom.com/intercom-api-reference).\n\n`API Documentation \u003chttps://developers.intercom.com/intercom-api-reference/reference\u003e`__.\n\n`Package\nDocumentation \u003chttp://readthedocs.org/docs/python-intercom/\u003e`__.\n\nUpgrading information\n---------------------\n\nVersion 3 of python-intercom is **not backwards compatible** with\nprevious versions.\n\nVersion 3 moves away from a global setup approach to the use of an\nIntercom Client.\n\nInstallation\n------------\n\n::\n\n    pip install python-intercom\n\nBasic Usage\n-----------\n\nConfigure your client\n~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n    from intercom.client import Client\n    intercom = Client(personal_access_token='my_personal_access_token')\n\nNote that certain resources will require an extended scope access token : `Setting up Personal Access Tokens \u003chttps://developers.intercom.com/docs/personal-access-tokens\u003e`_\n\nResources\n~~~~~~~~~\n\nResources this API supports:\n\n::\n\n    https://api.intercom.io/users\n    https://api.intercom.io/contacts\n    https://api.intercom.io/companies\n    https://api.intercom.io/counts\n    https://api.intercom.io/tags\n    https://api.intercom.io/notes\n    https://api.intercom.io/segments\n    https://api.intercom.io/events\n    https://api.intercom.io/conversations\n    https://api.intercom.io/messages\n    https://api.intercom.io/subscriptions\n    https://api.intercom.io/jobs\n    https://api.intercom.io/bulk\n\nExamples\n~~~~~~~~\n\nUsers\n^^^^^\n\n.. code:: python\n\n    # Find user by email\n    user = intercom.users.find(email=\"bob@example.com\")\n    # Find user by user_id\n    user = intercom.users.find(user_id=\"1\")\n    # Find user by id\n    user = intercom.users.find(id=\"1\")\n    # Create a user\n    user = intercom.users.create(email=\"bob@example.com\", name=\"Bob Smith\")\n    # Delete a user\n    user = intercom.users.find(id=\"1\")\n    deleted_user = intercom.users.delete(user)\n    # Update custom_attributes for a user\n    user.custom_attributes[\"average_monthly_spend\"] = 1234.56\n    intercom.users.save(user)\n    # Perform incrementing\n    user.increment('karma')\n    intercom.users.save(user)\n    # Iterate over all users\n    for user in intercom.users.all():\n        ...\n\nAdmins\n^^^^^^\n\n.. code:: python\n\n    # Iterate over all admins\n    for admin in intercom.admins.all():\n        ...\n\nCompanies\n^^^^^^^^^\n\n.. code:: python\n\n    # Add a user to one or more companies\n    user = intercom.users.find(email='bob@example.com')\n    user.companies = [\n        {'company_id': 6, 'name': 'Intercom'},\n        {'company_id': 9, 'name': 'Test Company'}\n    ]\n    intercom.users.save(user)\n    # You can also pass custom attributes within a company as you do this\n    user.companies = [\n        {\n            'id': 6,\n            'name': 'Intercom',\n            'custom_attributes': {\n                'referral_source': 'Google'\n            }\n        }\n    ]\n    intercom.users.save(user)\n    # Find a company by company_id\n    company = intercom.companies.find(company_id='44')\n    # Find a company by name\n    company = intercom.companies.find(name='Some company')\n    # Find a company by id\n    company = intercom.companies.find(id='41e66f0313708347cb0000d0')\n    # Update a company\n    company.name = 'Updated company name'\n    intercom.companies.save(company)\n    # Iterate over all companies\n    for company in intercom.companies.all():\n        ...\n    # Get a list of users in a company\n    intercom.companies.users(company.id)\n\nTags\n^^^^\n\n.. code:: python\n\n    # Tag users\n    tag = intercom.tags.tag(name='blue', users=[{'email': 'test1@example.com'}])\n    # Untag users\n    intercom.tags.untag(name='blue', users=[{'user_id': '42ea2f1b93891f6a99000427'}])\n    # Iterate over all tags\n    for tag in intercom.tags.all():\n        ...\n    # Tag companies\n    tag = intercom.tags.tag(name='blue', companies=[{'id': '42ea2f1b93891f6a99000427'}])\n\nSegments\n^^^^^^^^\n\n.. code:: python\n\n    # Find a segment\n    segment = intercom.segments.find(id=segment_id)\n    # Iterate over all segments\n    for segment in intercom.segments.all():\n        ...\n\nNotes\n^^^^^\n\n.. code:: python\n\n    # Find a note by id\n    note = intercom.notes.find(id=note)\n    # Create a note for a user\n    note = intercom.notes.create(\n        body=\"\u003cp\u003eText for the note\u003c/p\u003e\",\n        email='joe@example.com')\n    # Iterate over all notes for a user via their email address\n    for note in intercom.notes.find_all(email='joe@example.com'):\n        ...\n    # Iterate over all notes for a user via their user_id\n    for note in intercom.notes.find_all(user_id='123'):\n        ...\n\nConversations\n^^^^^^^^^^^^^\n\n.. code:: python\n\n    # FINDING CONVERSATIONS FOR AN ADMIN\n    # Iterate over all conversations (open and closed) assigned to an admin\n    for convo in intercom.conversations.find_all(type='admin', id='7'):\n        ...\n    # Iterate over all open conversations assigned to an admin\n    for convo in intercom.conversations.find_all(type='admin', id=7, open=True):\n        ...\n    # Iterate over closed conversations assigned to an admin\n    for convo intercom.conversations.find_all(type='admin', id=7, open=False):\n        ...\n    # Iterate over closed conversations for assigned an admin, before a certain\n    # moment in time\n    for convo in intercom.conversations.find_all(\n            type='admin', id= 7, open= False, before=1374844930):\n        ...\n\n    # FINDING CONVERSATIONS FOR A USER\n    # Iterate over all conversations (read + unread, correct) with a user based on\n    # the users email\n    for convo in intercom.onversations.find_all(email='joe@example.com',type='user'):\n        ...\n    # Iterate over through all conversations (read + unread) with a user based on\n    # the users email\n    for convo in intercom.conversations.find_all(\n            email='joe@example.com', type='user', unread=False):\n        ...\n    # Iterate over all unread conversations with a user based on the users email\n    for convo in intercom.conversations.find_all(\n            email='joe@example.com', type='user', unread=true):\n        ...\n\n    # FINDING A SINGLE CONVERSATION\n    conversation = intercom.conversations.find(id='1')\n\n    # INTERACTING WITH THE PARTS OF A CONVERSATION\n    # Getting the subject of a part (only applies to email-based conversations)\n    conversation.rendered_message.subject\n    # Get the part_type of the first part\n    conversation.conversation_parts[0].part_type\n    # Get the body of the second part\n    conversation.conversation_parts[1].body\n\n    # REPLYING TO CONVERSATIONS\n    # User (identified by email) replies with a comment\n    intercom.conversations.reply(\n        type='user', email='joe@example.com',\n        message_type='comment', body='foo')\n    # Admin (identified by email) replies with a comment\n    intercom.conversations.reply(\n        type='admin', email='bob@example.com',\n        message_type='comment', body='bar')\n    # User (identified by email) replies with a comment and attachment\n    intercom.conversations.reply(id=conversation.id, type='user', email='joe@example.com', message_type='comment', body='foo', attachment_urls=['http://www.example.com/attachment.jpg'])\n\n    # Open\n    intercom.conversations.open(id=conversation.id, admin_id='123')\n\n    # Close\n    intercom.conversations.close(id=conversation.id, admin_id='123')\n\n    # Assign\n    intercom.conversations.assign(id=conversation.id, admin_id='123', assignee_id='124')\n\n    # Reply and Open\n    intercom.conversations.reply(id=conversation.id, type='admin', admin_id='123', message_type='open', body='bar')\n\n    # Reply and Close\n    intercom.conversations.reply(id=conversation.id, type='admin', admin_id='123', message_type='close', body='bar')\n\n    # ASSIGNING CONVERSATIONS TO ADMINS\n    intercom.conversations.reply(id=conversation.id, type='admin', assignee_id=assignee_admin.id, admin_id=admin.id, message_type='assignment')\n\n    # MARKING A CONVERSATION AS READ\n    intercom.conversations.mark_read(conversation.id)\n\nFull loading of an embedded entity\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n    # Given a conversation with a partial user, load the full user. This can be\n    # done for any entity\n    intercom.users.load(conversation.user)\n\nSending messages\n^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n    # InApp message from admin to user\n    intercom.messages.create(**{\n        \"message_type\": \"inapp\",\n        \"body\": \"What's up :)\",\n        \"from\": {\n            \"type\": \"admin\",\n            \"id\": \"1234\"\n        },\n        \"to\": {\n            \"type\": \"user\",\n            \"id\": \"5678\"\n        }\n    })\n\n    # Email message from admin to user\n    intercom.messages.create(**{\n        \"message_type\": \"email\",\n        \"subject\": \"Hey there\",\n        \"body\": \"What's up :)\",\n        \"template\": \"plain\", # or \"personal\",\n        \"from\": {\n            \"type\": \"admin\",\n            \"id\": \"1234\"\n        },\n        \"to\": {\n            \"type\": \"user\",\n            \"id\": \"536e564f316c83104c000020\"\n        }\n    })\n\n    # Message from a user\n    intercom.messages.create(**{\n        \"from\": {\n            \"type\": \"user\",\n            \"id\": \"536e564f316c83104c000020\"\n        },\n        \"body\": \"halp\"\n    })\n\n    # Message from admin to contact\n    intercom.messages.create(**{\n        'body': 'How can I help :)',\n        'from': {\n            'type': 'admin',\n            'id': '1234'\n        },\n        'to': {\n            'type': 'contact',\n            'id': '536e5643as316c83104c400671'\n        }\n    })\n\n    # Message from a contact\n    intercom.messages.create(**{\n        'from' =\u003e {\n            'type': 'contact',\n            'id': '536e5643as316c83104c400671'\n        },\n        'body': 'halp'\n    })\n\nEvents\n^^^^^^\n\n.. code:: python\n\n    import time\n\n    intercom.events.create(\n        event_name='invited-friend',\n        created_at=int(time.mktime(time.localtime())),\n        email=user.email,\n        metadata={\n            'invitee_email': 'pi@example.org',\n            'invite_code': 'ADDAFRIEND',\n            'found_date': 12909364407\n        }\n    )\n\n    # Retrieve event list for user with id:'123abc'\n    intercom.events.find_all(type='user', \"intercom_user_id\"=\"123abc)\n\nMetadata Objects support a few simple types that Intercom can present on\nyour behalf\n\n.. code:: python\n\n    current_user = intercom.users.find(id=\"1\")\n\n    intercom.events.create(\n        event_name=\"placed-order\",\n        email=current_user.email,\n        created_at=1403001013,\n        metadata={\n            'order_date': time.mktime(time.localtime()),\n            'stripe_invoice': 'inv_3434343434',\n            'order_number': {\n                'value': '3434-3434',\n                'url': 'https://example.org/orders/3434-3434'\n            },\n            'price': {\n                'currency': 'usd',\n                'amount': 2999\n            }\n        }\n    )\n\nThe metadata key values in the example are treated as follows-\n\n-  order\\_date: a Date (key ends with '\\_date').\n-  stripe\\_invoice: The identifier of the Stripe invoice (has a\n   'stripe\\_invoice' key)\n-  order\\_number: a Rich Link (value contains 'url' and 'value' keys)\n-  price: An Amount in US Dollars (value contains 'amount' and\n   'currency' keys)\n\nContacts\n^^^^^^^^\n\nContacts represent logged out users of your application.\n\n.. code:: python\n\n    # Create a contact\n    contact = intercom.leads.create(email=\"some_contact@example.com\")\n\n    # Update a contact\n    contact.custom_attributes['foo'] = 'bar'\n    intercom.leads.save(contact)\n\n    # Find contacts by email\n    contacts = intercom.leads.find_all(email=\"some_contact@example.com\")\n\n    # Merge a contact into a user\n    user = intercom.users.find(id=\"1\")\n    intercom.leads.convert(contact, user)\n\n    # Delete a contact\n    intercom.leads.delete(contact)\n\nCounts\n^^^^^^\n\n.. code:: python\n\n    # App-wide counts\n    intercom.counts.for_app()\n\n    # Users in segment counts\n    intercom.counts.for_type(type='user', count='segment')\n\nSubscriptions\n~~~~~~~~~~~~~\n\nSubscribe to events in Intercom to receive webhooks.\n\n.. code:: python\n\n    # create a subscription\n    intercom.subscriptions.create(url='http://example.com', topics=['user.created'])\n\n    # fetch a subscription\n    intercom.subscriptions.find(id='nsub_123456789')\n\n    # list subscriptions\n    intercom.subscriptions.all():\n        ...\n\nErrors\n~~~~~~\n\nYou do not need to deal with the HTTP response from an API call\ndirectly. If there is an unsuccessful response then an error that is a\nsubclass of ``intercom.Error`` will be raised. If desired, you can get\nat the http\\_code of an ``Error`` via it's ``http_code`` method.\n\nThe list of different error subclasses are listed below. As they all\ninherit off ``IntercomError`` you can choose to except ``IntercomError``\nor the more specific error subclass:\n\n.. code:: python\n\n    AuthenticationError\n    ServerError\n    ServiceUnavailableError\n    ServiceConnectionError\n    ResourceNotFound\n    BadGatewayError\n    BadRequestError\n    RateLimitExceeded\n    MultipleMatchingUsersError\n    HttpError\n    UnexpectedError\n\nRate Limiting\n~~~~~~~~~~~~~\n\nCalling your clients ``rate_limit_details`` returns a dict that contains\ndetails about your app's current rate limit.\n\n.. code:: python\n\n    intercom.rate_limit_details\n    # {'limit': 180, 'remaining': 179, 'reset_at': datetime.datetime(2014, 10, 07, 14, 58)}\n\nRunning the Tests\n-----------------\n\nUnit tests:\n\n.. code:: bash\n\n    nosetests tests/unit\n\nIntegration tests:\n\n.. code:: bash\n\n    INTERCOM_PERSONAL_ACCESS_TOKEN=xxx nosetests tests/integration\n\n.. |PyPI Version| image:: https://img.shields.io/pypi/v/python-intercom.svg\n   :target: https://pypi.python.org/pypi/python-intercom\n.. |PyPI Downloads| image:: https://img.shields.io/pypi/dm/python-intercom.svg\n   :target: https://pypi.python.org/pypi/python-intercom\n.. |Travis CI Build| image:: https://travis-ci.org/jkeyes/python-intercom.svg\n   :target: https://travis-ci.org/jkeyes/python-intercom\n.. |Coverage Status| image:: https://coveralls.io/repos/github/jkeyes/python-intercom/badge.svg?branch=master\n   :target: https://coveralls.io/github/jkeyes/python-intercom?branch=master\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintercom%2Fpython-intercom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintercom%2Fpython-intercom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintercom%2Fpython-intercom/lists"}