tap-intercom

This is a Singer tap that produces JSON-formatted data following the Singer spec.

This tap:

• Pulls raw data from the Intercom v2.0 API
• Extracts the following resources:
  • Admins
  • Companies
  • Conversations
    • Conversation Parts
  • Data Attributes
  • Segments
  • Tags
  • Teams
• Outputs the schema for each resource
• Incrementally pulls data based on the input state

Streams

admins

• Endpoint: https://api.intercom.io/admins
• Primary key fields: id
• Foreign key fields: team_ids
• Replication strategy: FULL_TABLE
• Transformations: none

companies

• Endpoint: https://api.intercom.io/companies
• Primary key fields: id
• Foreign key fields: segments > id, tags > id
• Replication strategy: INCREMENTAL (query all, filter results)
  • Bookmark: updated_at (date-time)
• Transformations: de-nest segments, tags

conversations

• Endpoint: https://api.intercom.io/conversations
• Primary key fields: id
• Foreign key fields: assignee > id, author > id, customer > id, customers > id, teammate > id, tags > id, user > id
• Replication strategy: INCREMENTAL (query all, filter results)
  • Sort: updated_at asc
  • Bookmark: updated_at (date-time)
• Transformations: de-nest customers, tags

conversation_parts

• Endpoint: https://api.intercom.io/conversations/{conversation_id}
• Primary key fields: id
• Foreign key fields: conversation_id, author > id
• Replication strategy: FULL_TABLE (ALL for each changed parent Conversation)
• Transformations: Conversation parts with parent conversation_id

segments

• Endpoint: https://api.intercom.io/segments
• Primary key fields: id
• Foreign key fields: none
• Replication strategy: INCREMENTAL (query all, filter results)
  • Bookmark: updated_at (date-time)
• Transformations: none

tags

• Endpoint: https://api.intercom.io/tags
• Primary key fields: id
• Foreign key fields: none
• Replication strategy: FULL_TABLE
• Transformations: none

teams

• Endpoint: https://api.intercom.io/teams
• Primary key fields: id
• Foreign key fields: admin_ids
• Replication strategy: FULL_TABLE
• Transformations: none

Authentication

Quick Start

1. Install

   Clone this repository, and then install using setup.py. We recommend using a virtualenv:

   > virtualenv -p python3 venv
   > source venv/bin/activate
   > python setup.py install
   OR
   > cd .../tap-intercom
   > pip install .

2. Dependent libraries The following dependent libraries were installed.

   > pip install singer-python
   > pip install singer-tools
   > pip install target-stitch
   > pip install target-json
   

   • singer-tools
   • target-stitch

3. Create your tap's config.json file. Intercom Authentication Types explains how to get an access_token. Make sure your OAuth Scope allows Read access to the endpoints above. Additionally, your App should use API Version v1.4.

   {
       "access_token": "YOUR_API_ACCESS_TOKEN",
       "start_date": "2019-01-01T00:00:00Z",
   }

   Optionally, also create a state.json file. currently_syncing is an optional attribute used for identifying the last object to be synced in case the job is interrupted mid-stream. The next run would begin where the last job left off.

   {
       "bookmarks": {
         "companies": {
           "updated_at": "2020-04-30T14:37:41+00:00"
         },
         "contacts": {
           "updated_at": "2020-04-30T16:21:56+00:00"
         },
         "conversations": {
           "updated_at": "2020-04-30T09:38:38+00:00"
         },
         "segments": {
           "updated_at": "2020-02-20T12:31:38+00:00"
         }
       }
   }

4. Run the Tap in Discovery Mode This creates a catalog.json for selecting objects/fields to integrate:

   tap-intercom --config config.json --discover > catalog.json

   See the Singer docs on discovery mode here.

5. Run the Tap in Sync Mode (with catalog) and write out to state file

   For Sync mode:

   > tap-intercom --config tap_config.json --catalog catalog.json > state.json
   > tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

   To load to json files to verify outputs:

   > tap-intercom --config tap_config.json --catalog catalog.json | target-json > state.json
   > tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

   To pseudo-load to Stitch Import API with dry run:

   > tap-intercom --config tap_config.json --catalog catalog.json | target-stitch --config target_config.json --dry-run > state.json
   > tail -1 state.json > state.json.tmp && mv state.json.tmp state.json