# HelpScout

### Snapshot

| Features                        | Details                                      |
| ------------------------------- | -------------------------------------------- |
| Release Status                  | Released                                     |
| Source API Version              | v2                                           |
| Table Selection                 | Yes                                          |
| Column Selection                | Yes                                          |
| Edit Integration                | Yes                                          |
| Replication Type Selection      | No                                           |
| Authentication Parameters       | <p>Helpscout Email<br>Helpscout password</p> |
| Replication Type                | Key based Replication                        |
| Replication Key                 | DATE                                         |
| Suggested Replication Frequency | 24 hrs                                       |

Tables/APIs Supported --- | --- Conversations | Customers Tags | ConversationsReceivedMessages ConversationsDrilldownReport | CompanyOverallReport ConversationsVolumesByChannelReport | DocsOverallReport CompanyConversationsReport | CustomerHappinessOverallReport ProductivityOverallReport | ConversationsOverallReport Users | Emailreport Chatreport | UserOverallReport UserConversationHistoryReport | UserConversationReport UserHappinessReport | UserHappinessDrilldown CustomerHappinessRatingsReport

### Integrate Helpscout with Daton

1. Signin to Daton
2. Select Helpscout from Integrations page
3. Provide Integration Name Replication Frequency and History. Integration name would be used in creating tables for the integration and cannot be changed later
4. Provide your Helpscout account Email and Password.
5. After providing the Email,password to authorize Daton to periodically extract data from Helpscout.
6. Post successful authentication you will be prompted to choose from the list of available tables
7. Then select all required fields for each table
8. Submit the integration.

### Workflow

1. Integrations would be in Pending state initially and will be moved to Active state as soon as the first job loads data successfully on to the configured warehouse
2. Users would be able to edit/pause/re-activate/delete integration anytime
3. Users can view job status and process logs from the integration details page by clicking on the integration name from the active list

### Helpscout Data

**Conversations**

Purpose: List and filter conversations.

Source API Documentation  <https://developer.helpscout.com/mailbox-api/endpoints/conversations/list/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name                 | Target Datatype |
| -------------------- | --------------- |
| embed                | STRING          |
| status               | STRING          |
| id                   | NUMERIC         |
| number               | NUMERIC         |
| threads              | NUMERIC         |
| type                 | STRING          |
| folderId             | NUMERIC         |
| status               | STRING          |
| state                | STRING          |
| subject              | STRING          |
| preview              | STRING          |
| mailboxId            | NUMERIC         |
| assignee             | RECORD          |
| createdBy            | RECORD          |
| createdAt            | TIMESTAMP       |
| closedBy             | NUMERIC         |
| closedByUser         | RECORD          |
| userUpdatedAt        | TIMESTAMP       |
| customerWaitingSince | RECORD          |
| source               | RECORD          |
| tags                 | RECORD          |
| cc                   | STRING          |
| bcc                  | STRING          |
| primaryCustomer      | RECORD          |
| customFields         | STRING          |
| \_embedded           | RECORD          |
| \_links              | RECORD          |

**Customers**

Purpose:Request parameters can be used to filter customers.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/customers/list/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name         | Target Datatype |
| ------------ | --------------- |
| id           | NUMERIC         |
| firstName    | STRING          |
| lastName     | STRING          |
| gender       | STRING          |
| jobTitle     | STRING          |
| location     | STRING          |
| organization | STRING          |
| photoType    | STRING          |
| photoUrl     | STRING          |
| createdAt    | TIMESTAMP       |
| updatedAt    | TIMESTAMP       |
| background   | STRING          |
| \_embedded   | RECORD          |
| \_links      | RECORD          |

**Tags**

Purpose:Returns a list of tags used across all mailboxes. Tags are returned in alphabetical order.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/tags/list/>

Replication: Full Replication

Replication Key: NA

**Fields**

| Name        | Target Datatype |
| ----------- | --------------- |
| id          | NUMERIC         |
| slug        | STRING          |
| name        | STRING          |
| color       | STRING          |
| createdAt   | TIMESTAMP       |
| ticketCount | NUMERIC         |

**ConversationsReceivedMessages**

Purpose: The received messages report provides a summary of the volume of received messages over a given time range. Only messages from customers are counted.

Source API Documentation  <https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-received-messages/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name        | Target Datatype |
| ----------- | --------------- |
| viewBy      | STRING          |
| channelType | STRING          |
| date        | TIMESTAMP       |
| messages    | NUMERIC         |

**ConversationsDrilldownReport**

Purpose:This report is similar to the Conversations Report, but instead of returning statistics about conversation volume, it drills down and returns the conversation data that makes up the Conversations Report.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-drilldown/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name             | Target Datatype |
| ---------------- | --------------- |
| startDate        | TIMESTAMP       |
| endDate          | TIMESTAMP       |
| channelType      | STRING          |
| id               | NUMERIC         |
| number           | NUMERIC         |
| attachments      | BOOLEAN         |
| subject          | STRING          |
| status           | STRING          |
| threadCount      | NUMERIC         |
| preview          | STRING          |
| customerName     | STRING          |
| customerEmail    | STRING          |
| customerIds      | STRING          |
| tags             | RECORD          |
| modifiedAt       | TIMESTAMP       |
| type             | STRING          |
| waitingSince     | TIMESTAMP       |
| waitingSinceType | NUMERIC         |
| mailboxid        | NUMERIC         |
| assignedid       | NUMERIC         |

**CompanyOverallReport**

Purpose: The company report provides statistics about your company performance over a given time range. You may optionally specify two time ranges to see how performance changed between the two ranges.

Source API Documentation  <https://developer.helpscout.com/mailbox-api/endpoints/reports/company/reports-company-overall/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name        | Target Datatype |
| ----------- | --------------- |
| channelType | STRING          |
| filterTags  | STRING          |
| current     | RECORD          |
| users       | RECORD          |

**ConversationsVolumesByChannelReport**

Purpose:This report shows conversation volumes split by chat, phone and email channels.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-volume-by-channel/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name        | Target Datatype |
| ----------- | --------------- |
| viewBy      | STRING          |
| channelType | STRING          |
| date        | TIMESTAMP       |
| chat        | NUMERIC         |
| email       | NUMERIC         |
| phone       | NUMERIC         |

**DocsOverallReport**

Purpose: The Docs report provides statistics about Docs usage (searches, top articles, etc.) over a given time range.

Source API Documentation  <https://developer.helpscout.com/mailbox-api/endpoints/reports/docs/reports-docs-overall/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name            | Target Datatype |
| --------------- | --------------- |
| startDate       | TIMESTAMP       |
| endDate         | TIMESTAMP       |
| current         | RECORD          |
| topCategories   | STRING          |
| topArticles     | STRING          |
| popularSearches | STRING          |
| failedSearches  | RECORD          |

**CompanyConversationsReport**

Purpose:This report is similar to the Company Report, but instead of returning statistics about the company, it drills down and returns the conversation data that makes up the Company Report.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/company/reports-company-drilldown/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name             | Target Datatype |
| ---------------- | --------------- |
| range            | STRING          |
| startDate        | TIMESTAMP       |
| endDate          | TIMESTAMP       |
| channelType      | STRING          |
| id               | NUMERIC         |
| number           | NUMERIC         |
| attachments      | BOOLEAN         |
| subject          | STRING          |
| status           | STRING          |
| threadCount      | NUMERIC         |
| preview          | STRING          |
| customerName     | STRING          |
| customerEmail    | STRING          |
| customerIds      | STRING          |
| modifiedAt       | TIMESTAMP       |
| type             | STRING          |
| waitingSince     | TIMESTAMP       |
| waitingSinceType | NUMERIC         |
| closedAt         | TIMESTAMP       |
| mailboxid        | NUMERIC         |
| assignedid       | NUMERIC         |

**CustomerHappinessOverallReport**

Purpose:The happiness report provides information about how many Great, Okay, and Not Good ratings your company received for each period in a specified time range.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/happiness/reports-happiness-overall/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name                          | Target Datatype |
| ----------------------------- | --------------- |
| startDate                     | TIMESTAMP       |
| endDate                       | TIMESTAMP       |
| channelType                   | STRING          |
| okay                          | NUMERIC         |
| notGoodCount                  | NUMERIC         |
| happinessScore                | NUMERIC         |
| totalConversationsWithRatings | NUMERIC         |
| ratingsCount                  | NUMERIC         |
| ratingsPercent                | NUMERIC         |
| notGood                       | NUMERIC         |
| great                         | NUMERIC         |
| greatCount                    | NUMERIC         |
| okayCount                     | NUMERIC         |

**ProductivityOverallReport**

Purpose: The productivity report provides a snapshot of productivity over a given time range.

Source API Documentation  <https://developer.helpscout.com/mailbox-api/endpoints/reports/productivity/reports-productivity-overall/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name              | Target Datatype |
| ----------------- | --------------- |
| startDate         | TIMESTAMP       |
| endDate           | TIMESTAMP       |
| officeHours       | STRING          |
| channelType       | STRING          |
| current           | RECORD          |
| responseTime      | RECORD          |
| handleTime        | RECORD          |
| firstResponseTime | RECORD          |
| resolutionTime    | RECORD          |
| repliesToResolve  | RECORD          |

**ConversationsOverallReport**

Purpose:The conversations report provides statistics about conversation volume over a given time range.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-overall/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name          | Target Datatype |
| ------------- | --------------- |
| channelType   | STRING          |
| startDate     | TIMESTAMP       |
| endDate       | TIMESTAMP       |
| workflows     | RECORD          |
| replies       | RECORD          |
| tags          | RECORD          |
| customers     | RECORD          |
| filterTags    | RECORD          |
| busiestDay    | RECORD          |
| busyTimeEnd   | NUMERIC         |
| busyTimeStart | NUMERIC         |
| customFields  | RECORD          |
| current       | RECORD          |
| tagIds        | STRING          |

**Users**

Purpose: To get all the users.

Source API Documentation  <https://developer.helpscout.com/mailbox-api/endpoints/users/list/>

Replication: Full Replication

Replication Key: NA

**Fields**

| Name            | Target Datatype |
| --------------- | --------------- |
| id              | NUMERIC         |
| firstName       | STRING          |
| lastName        | STRING          |
| email           | STRING          |
| role            | STRING          |
| timezone        | STRING          |
| createdAt       | STRING          |
| updatedAt       | STRING          |
| type            | STRING          |
| mention         | STRING          |
| initials        | STRING          |
| jobTitle        | STRING          |
| phone           | STRING          |
| alternateEmails | STRING          |
| \_links         | RECORD          |

**Emailreport**

Purpose:Our Email report measures efficiency working with email conversations.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/email/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name              | Target Datatype |
| ----------------- | --------------- |
| officeHours       | STRING          |
| filterTags        | STRING          |
| current           | RECORD          |
| responseTime      | RECORD          |
| handleTime        | RECORD          |
| firstResponseTime | RECORD          |
| resolutionTime    | RECORD          |
| repliesToResolve  | RECORD          |

**Chatreport**

Purpose:The Chat report is all about seeing volume, efficiency, and team productivity when using Beacon with live chat over time.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/chat/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name            | Target Datatype |
| --------------- | --------------- |
| officeHours     | STRING          |
| current         | RECORD          |
| waitTime        | RECORD          |
| responseTime    | RECORD          |
| messagesPerChat | RECORD          |
| duration        | RECORD          |

**UserOverallReport**

Purpose:The report provides a snapshot of a user or team activity over a specified time range.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name        | Target Datatype |
| ----------- | --------------- |
| officeHours | STRING          |
| channelType | STRING          |
| filterTags  | STRING          |
| user        | RECORD          |
| current     | RECORD          |

**UserConversationHistoryReport**

Purpose:The conversation history report provides details about a user’s conversations for over a specified time range.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-conversation-history/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name        | Target Datatype |
| ----------- | --------------- |
| startDate   | TIMESTAMP       |
| endDate     | TIMESTAMP       |
| officeHours | STRING          |
| channelType | STRING          |
| status      | STRING          |
| id          | NUMERIC         |
| type        | STRING          |
| number      | NUMERIC         |
| customers   | RECORD          |

**UserConversationReport**

Purpose:This report is similar to the User Report, but instead of returning statistics about users, it drills down and returns the conversation data that makes up the User Report.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-drilldown/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name             | Target Datatype |
| ---------------- | --------------- |
| startDate        | TIMESTAMP       |
| endDate          | TIMESTAMP       |
| channelType      | STRING          |
| id               | NUMERIC         |
| number           | NUMERIC         |
| attachments      | BOOLEAN         |
| subject          | STRING          |
| status           | STRING          |
| threadCount      | NUMERIC         |
| preview          | STRING          |
| customerName     | STRING          |
| customerEmail    | STRING          |
| customerIds      | STRING          |
| tags             | RECORD          |
| modifiedAt       | TIMESTAMP       |
| type             | STRING          |
| waitingSince     | TIMESTAMP       |
| waitingSinceType | NUMERIC         |
| mailboxid        | NUMERIC         |
| assignedid       | NUMERIC         |

**UserHappinessReport**

Purpose:The happiness report provides information about how many Great, Okay, and Not Good ratings a user received for each period in a specified time range.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-happiness/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name        | Target Datatype |
| ----------- | --------------- |
| startDate   | TIMESTAMP       |
| endDate     | TIMESTAMP       |
| channelType | STRING          |
| current     | RECORD          |

**UserHappinessDrilldown**

Purpose:The user ratings report provides a user’s ratings for over a specified time range.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-happiness-drilldown/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name               | Target Datatype |
| ------------------ | --------------- |
| startDate          | TIMESTAMP       |
| endDate            | TIMESTAMP       |
| ratingType         | STRING          |
| channelType        | STRING          |
| number             | NUMERIC         |
| threadid           | NUMERIC         |
| threadCreatedAt    | TIMESTAMP       |
| id                 | NUMERIC         |
| type               | STRING          |
| ratingId           | NUMERIC         |
| ratingCustomerId   | NUMERIC         |
| ratingComments     | STRING          |
| ratingCreatedAt    | TIMESTAMP       |
| ratingCustomerName | STRING          |
| ratingUserId       | NUMERIC         |
| ratingUserName     | STRING          |

**CustomerHappinessRatingsReport**

Purpose:The happiness ratings report provides a company’s ratings for over a specified time range.

Source API Documentation <https://developer.helpscout.com/mailbox-api/endpoints/reports/happiness/reports-happiness-ratings/>

Replication: Key-Based Replication

Replication Key: lastRunDate

**Fields**

| Name               | Target Datatype |
| ------------------ | --------------- |
| rating             | STRING          |
| startDate          | TIMESTAMP       |
| endDate            | TIMESTAMP       |
| channelType        | STRING          |
| number             | NUMERIC         |
| threadid           | NUMERIC         |
| threadCreatedAt    | TIMESTAMP       |
| id                 | NUMERIC         |
| type               | STRING          |
| ratingId           | NUMERIC         |
| ratingCustomerId   | NUMERIC         |
| ratingComments     | STRING          |
| ratingCreatedAt    | TIMESTAMP       |
| ratingCustomerName | STRING          |
| ratingUserId       | NUMERIC         |
| ratingUserName     | STRING          |