HubSpot/HubSpot_Get_deal_brief.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "27486f01-77c3-4774-a098-29c706202d62",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "<img width=\"8%\" alt=\"HubSpot.png\" src=\"https://raw.githubusercontent.com/jupyter-naas/awesome-notebooks/master/.github/assets/logos/HubSpot.png\" style=\"border-radius: 15%\">"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85c6497e-923f-41fa-b85b-81f47a5ab9c7",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "# HubSpot - Get deal brief\n",
    "<a href=\"https://bit.ly/3JyWIk6\">Give Feedback</a> | <a href=\"https://github.com/jupyter-naas/awesome-notebooks/issues/new?assignees=&labels=bug&template=bug_report.md&title=HubSpot+-+Get+deal+brief:+Error+short+description\">Bug report</a>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "661f554e-7065-4101-81c2-9e799a812b67",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**Tags:** #hubspot #deal #activity #notes #emails #communications #meetings #snippet"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a852a18f-e277-4aa5-bdec-8dd1fccb57d2",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**Author:** [Florent Ravenel](https://www.linkedin.com/in/florent-ravenel)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6dd7c05c-17ed-459f-88a8-3c6629b80cde",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**Last update:** 2023-09-22 (Created: 2023-09-22)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7dcfd269-589b-4199-b521-6884053ff935",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**Description:** This notebook illustrates the process of obtaining a deal brief in HubSpot. It fetches detailed detail information, along with all related activities between you and your sales team. These activities may include emails, notes, meetings, and communications via LinkedIn, WhatsApp, and SMS. The output is conveniently delivered as a text file."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0da5ca2d-a6a1-424c-b41f-391428555503",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "**References:**\n",
    "- [HubSpot API - Deals](https://developers.hubspot.com/docs/api/crm/deals)\n",
    "- [HubSpot API - Associations v4](https://developers.hubspot.com/docs/api/crm/associations)\n",
    "- [HubSpot API - Communications](https://developers.hubspot.com/docs/api/crm/communications)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c6e5050-800a-4f05-a1d2-5a682c54e069",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "## Input"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c27222b-7468-4daa-9a77-c446aaf66f72",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Import libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "a3fad6df-27f3-4e13-a934-083468860bf3",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": [
    "import requests\n",
    "import naas\n",
    "from naas_drivers import hubspot\n",
    "import pandas as pd\n",
    "import os\n",
    "pd.set_option('display.max_colwidth', None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17d095ea-e80c-4d8d-896b-271f3e0ea121",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Setup variables\n",
    "**Mandatory**\n",
    "\n",
    "[Get your HubSpot Access token](https://knowledge.hubspot.com/articles/kcs_article/integrations/how-do-i-get-my-hubspot-api-key)\n",
    "- `hs_access_token`: This variable stores an access token used for accessing the HubSpot API.\n",
    "- `deal_url`: This variable stores the HubSpot deal URL.\n",
    "\n",
    "**Optional**\n",
    "- `deal_properties`: It represents the list of properties to retrieve from your deal\n",
    "- `associations`: It represents the list of associations to get from your deal\n",
    "- `output_dir`: This parameter specifies the directory path where the output text file will be stored."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "13df3457-9ca4-4a77-ace7-2cd5a386362d",
   "metadata": {
    "papermill": {},
    "tags": [
     "parameters"
    ]
   },
   "outputs": [],
   "source": [
    "# Mandatory\n",
    "hs_access_token = naas.secret.get(\"HS_ACCESS_TOKEN\") or \"YOUR_HS_ACCESS_TOKEN\"\n",
    "deal_url = \"https://app.hubspot.com/contacts/2474088/record/0-3/15220482319/\" # \"https://app.hubspot.com/contacts/xxxxx/record/0-1/xxxxx\"\n",
    "\n",
    "# Optional\n",
    "deal_properties = [\"hs_object_id\", \"dealname\", \"dealstage\", 'amount']\n",
    "associations = [\"notes\", \"emails\", \"meetings\", \"communications\"]\n",
    "output_dir = \"hubspot\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "58f1d275-a026-45a5-8629-9b5f1f8b038f",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "## Model"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6ef36c3-13ab-45e5-97fb-3ba6e4c2ff99",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Get deal ID from URL"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "c3588e3a-0829-485a-81c5-bcde7f137549",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": [
    "def get_contact_ID_from_URL(url):\n",
    "    # Init\n",
    "    uid = url\n",
    "    \n",
    "    # Check if URL is valid\n",
    "    if not url.startswith(\"https://app.hubspot.com/contacts/\"):\n",
    "        raise BaseException(\"HubSpot URL Invalid! It must start by https://app.hubspot.com/contacts/\")\n",
    "    \n",
    "    # Split URL to get ID\n",
    "    if \"/record/0-3/\" in url:\n",
    "        uid = url.split(\"/record/0-3/\")[-1].split(\"/\")[0]\n",
    "    return uid\n",
    "\n",
    "deal_id = get_contact_ID_from_URL(deal_url)\n",
    "print(\"Deal ID:\", deal_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dd600b6a-2298-421e-80d7-1d101e1aecb4",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Get contact details"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "9c5c7fdf-be1e-4b0c-8cc2-705b460d00f3",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": [
    "def retrieve_object_details(\n",
    "    token,\n",
    "    object_id,\n",
    "    object_type,\n",
    "    properties=None,\n",
    "):\n",
    "    # Init\n",
    "    data = []\n",
    "    params = {\n",
    "        \"archived\": \"false\"\n",
    "    }\n",
    "    \n",
    "    # Requests\n",
    "    if properties:\n",
    "        params[\"properties\"] = properties\n",
    "    headers = {\n",
    "        \"Content-Type\": \"application/json\",\n",
    "        \"Authorization\": f\"Bearer {token}\"\n",
    "    }\n",
    "    url = f\"https://api.hubapi.com/crm/v3/objects/{object_type}/{object_id}\"\n",
    "    \n",
    "    # Response\n",
    "    res = requests.get(url, headers=headers, params=params)\n",
    "    if res.status_code == 200:\n",
    "        data = res.json().get(\"properties\")\n",
    "    else:\n",
    "        print(res.text)\n",
    "    return pd.DataFrame([data])\n",
    "\n",
    "def create_activity_df(\n",
    "    token,\n",
    "    object_id,\n",
    "    activity,\n",
    "    properties_dict=None,\n",
    "):\n",
    "    # Init\n",
    "    properties = [x for x in properties_dict]\n",
    "    \n",
    "    # List activities\n",
    "    df = retrieve_object_details(\n",
    "        token,\n",
    "        object_id,\n",
    "        activity,\n",
    "        properties\n",
    "    )\n",
    "    if len(df) > 0:\n",
    "        df = df[properties]\n",
    "        \n",
    "    if len(df) > 0:\n",
    "        df = df.rename(columns=properties_dict)\n",
    "        if 'activity_type' not in df:\n",
    "            df.insert(loc=1, column=\"activity_type\", value=activity.upper())\n",
    "    \n",
    "    return df.reset_index(drop=True)\n",
    "\n",
    "def get_details(\n",
    "    hs_access_token,\n",
    "    hubspot_id,\n",
    "    properties,\n",
    "    associations\n",
    "):\n",
    "    # Init\n",
    "    message = \"DEAL:\\n\"\n",
    "    df = pd.DataFrame()\n",
    "    \n",
    "    # Get object\n",
    "    obj = hubspot.connect(hs_access_token).deals.get(\n",
    "        hubspot_id,\n",
    "        hs_properties=properties,\n",
    "        hs_associations=associations\n",
    "    )\n",
    "    \n",
    "    # Get properties\n",
    "    obj_properties = obj.get(\"properties\")\n",
    "    for p in properties:\n",
    "        message = f\"{message}- {p}: {obj_properties.get(p)}\\n\"\n",
    "    \n",
    "    # Get contact associations\n",
    "    obj_associations = obj.get(\"associations\")\n",
    "    for a in obj_associations:\n",
    "        results = obj_associations.get(a).get(\"results\")\n",
    "        for r in results:\n",
    "            if a == \"communications\":\n",
    "                properties_dict = {\n",
    "                    \"hs_object_id\": \"activity_hs_id\",\n",
    "                    \"hs_timestamp\": \"activity_date\",\n",
    "                    \"hs_communication_channel_type\": \"activity_type\",\n",
    "                    \"hs_body_preview\": \"activity_content\"\n",
    "                }\n",
    "            elif a == \"meetings\":\n",
    "                properties_dict = {\n",
    "                    \"hs_object_id\": \"activity_hs_id\",\n",
    "                    \"hs_timestamp\": \"activity_date\",\n",
    "                    \"hs_meeting_title\": \"activity_content\"\n",
    "                }\n",
    "            else:\n",
    "                properties_dict = {\n",
    "                    \"hs_object_id\": \"activity_hs_id\",\n",
    "                    \"hs_timestamp\": \"activity_date\",\n",
    "                    \"hs_body_preview\": \"activity_content\"\n",
    "                }\n",
    "            association_id = r.get(\"id\")\n",
    "            \n",
    "            # Create activity df\n",
    "            tmp_df = create_activity_df(\n",
    "                hs_access_token,\n",
    "                association_id,\n",
    "                a,\n",
    "                properties_dict\n",
    "            )\n",
    "            df = pd.concat([df, tmp_df])\n",
    "    \n",
    "    # Cleaning df\n",
    "    if len(df) > 0:\n",
    "        # Exclude empty or None value\n",
    "        df = df[~(df[\"activity_content\"].astype(str).isin([\"None\"]))]\n",
    "\n",
    "        # Format date\n",
    "        df[\"activity_date\"] = pd.to_datetime(df[\"activity_date\"]).dt.strftime(\"%Y-%m-%d %H:%M:%S\")\n",
    "        df = df.sort_values(by=\"activity_date\", ascending=False).reset_index(drop=True)\n",
    "            \n",
    "    # Create activity message\n",
    "    message = f\"{message}\\nACTIVITIES:\\n\"\n",
    "    for row in df.itertuples():\n",
    "        activity_date = row.activity_date\n",
    "        activity_type = row.activity_type\n",
    "        activity_content = row.activity_content.replace(\"\\xa0\\u200c\", \"\")\n",
    "        message = f\"{message}-{activity_date}: {activity_type} - {activity_content}\\n\"\n",
    "    return message, df.reset_index(drop=True)\n",
    "\n",
    "brief, df_activity = get_details(\n",
    "    hs_access_token,\n",
    "    deal_id,\n",
    "    deal_properties,\n",
    "    associations\n",
    ")\n",
    "print(brief)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e9729cd-8e75-4c13-a06c-87afb9923e53",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "source": [
    "## Output"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f09fcd0a-5b7f-4a96-9822-f4a6995a6ac0",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-08-21T14:13:58.779716Z",
     "iopub.status.busy": "2023-08-21T14:13:58.779474Z",
     "iopub.status.idle": "2023-08-21T14:13:58.784746Z",
     "shell.execute_reply": "2023-08-21T14:13:58.784135Z",
     "shell.execute_reply.started": "2023-08-21T14:13:58.779693Z"
    },
    "papermill": {},
    "tags": []
   },
   "source": [
    "### Save data to txt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "62e3f7af-5383-45fc-b5ec-31796a179f34",
   "metadata": {
    "papermill": {},
    "tags": []
   },
   "outputs": [],
   "source": [
    "def save_txt(output_dir, husbspot_id, txt):\n",
    "    # Create dirs\n",
    "    os.makedirs(output_dir, exist_ok=True)\n",
    "    \n",
    "    # Create path\n",
    "    file_path = os.path.join(output_dir, f\"{husbspot_id}_deal_brief.txt\")\n",
    "    \n",
    "    # Save file\n",
    "    file = open(file_path, 'w')  # Open the file in write mode ('w')\n",
    "    file.write(txt) # Write the text to the file\n",
    "    file.close() # Always remember to close the file\n",
    "    print(f\"File successfully saved: {file_path}\")\n",
    "    \n",
    "save_txt(output_dir, deal_id, brief)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.6"
  },
  "naas": {
   "notebook_id": "90427433669e0a447b5aa778552086cdcad6418e1e5a81c0cf6d7a333a430b3f",
   "notebook_path": "HubSpot/HubSpot_Get_deal_brief.ipynb"
  },
  "papermill": {
   "default_parameters": {},
   "environment_variables": {},
   "parameters": {},
   "version": "2.4.0"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}