Skip to main content

Quick Start: Connecting HubSpot

Go end to end from creating an Octopods account to seeing your first message land in the HubSpot inbox in about 5 minutes.

Written by Tarek Khalil

What you need

  • A HubSpot portal with admin access. You must be able to approve HubSpot apps and manage inboxes and custom channels in the portal.

  • The credentials or assets for the first channel you plan to connect. Telegram is the fastest to set up for a smoke test. If you already have Twilio, WhatsApp, Slack, Instagram, or Messenger configured, any of those work.

Step 1: Create your Octopods account

  1. Go to the Octopods sign-up page.

  2. Either click one of the SSO buttons (Google, Intercom, HubSpot, or Slack) or fill in the email, phone, and password form. Signing up with “Sign up with HubSpot” is fastest if you already have a HubSpot login.

  3. If you signed up with email and password, open the confirmation email from notifications@octopods.io and click Confirm My Account. If you signed up with SSO, you are already signed in.

For full detail, see Creating Your Octopods Account.

Step 2: Connect your HubSpot portal

After signing in, Octopods takes you to the Connected Workspaces page. On first sign-in, this page shows the welcome state with the heading “Thanks for signing up!” and a “Step 1 of 2” badge.

  1. Locate the Connect HubSpot card with the message “Link your HubSpot account”.

  2. Click Connect. Octopods redirects you to HubSpot.

  3. Sign in to HubSpot if you aren’t already.

  4. Select the HubSpot portal you want to connect.

  5. Review and approve the permissions Octopods is requesting. These cover reading and writing conversations, managing custom channels, reading and writing contacts, and (for Twilio and WhatsApp) reading and writing tickets.

  6. HubSpot redirects you back to Octopods. Your new HubSpot workspace appears on the Connected Workspaces page, identified as “Portal ID #”.

Step 3: Add your first channel

  1. Click your HubSpot workspace card to open it. You’ll land on the channels list for that workspace.

  2. Open the Add a Channel modal. On a HubSpot workspace this shows the Available Channels section.

  3. Pick the channel you want to connect. For a quick test, click Telegram.

  4. Follow the channel-specific setup. For Telegram, paste the bot token you got from BotFather.

  5. When prompted, select the HubSpot inbox you want this channel’s conversations to land in. You can pick any inbox your HubSpot user has access to.

  6. Octopods creates a custom channel in HubSpot for you, and your Telegram bot is now connected.

Step 4: Send your first message

Your workspace is now wired up end to end. Here’s how to confirm it works.

  1. Send a test inbound message. For Telegram, open a chat with your bot and send “hello”. For WhatsApp, send a message to the connected number. For SMS, text the connected number.

  2. Open your HubSpot inbox. The message appears as a new conversation, threaded against the matching contact if HubSpot can identify one.

  3. Reply to the conversation from HubSpot.

  4. Back on the channel, the reply arrives — from your bot, number, or page.

That’s the full round trip: an inbound message reached your HubSpot inbox as a conversation, and your reply reached the customer on the original channel.

HubSpot-specific details

A few things are worth knowing up front when you’re coming from HubSpot:

  • Each channel appears as a custom channel inside HubSpot. That means your team’s existing HubSpot automations, routing rules, and reporting can treat Octopods-connected channels like any other inbox source.

  • Inbox selection is per-channel. Each channel can be routed to a different HubSpot inbox if your team is organized that way.

  • Portal admin access is required. If you can’t approve the HubSpot app, a colleague with admin rights needs to complete the connection step.

Troubleshooting the quick start

  • HubSpot authorization fails. You need HubSpot admin access to approve the required scopes. Ask a colleague with admin rights to connect the portal.

  • No inbox to pick. If you don’t see any inboxes during channel setup, ask your HubSpot admin to grant your user access to at least one inbox, or create one.

  • Messages don’t appear in HubSpot. Confirm the channel’s status shows “Connected”, the correct HubSpot inbox was selected, and the test message was sent to the right destination.

  • Reply doesn’t reach the customer. Make sure you replied from the HubSpot inbox (not from an external client), and that the channel’s status is still “Connected”.

What’s next

Did this answer your question?