Before you start
You need:
A HubSpot Professional or Enterprise GTM seat. You need one to receive and reply to messages in the HubSpot inbox. HubSpot’s Free and Starter plans don’t include this.
A HubSpot workspace already connected to Octopods.
A Twilio account with an active SMS-capable phone number or alphanumeric sender.
Your Twilio Account SID and Auth Token from the Twilio Console home page.
For numbers sending to the United States: a registered A2P 10DLC (Application-to-Person messaging over 10-digit long code) brand and campaign (discussed below).
Admin access to the HubSpot portal with permission to grant additional HubSpot permissions.
At least one inbox already configured inside HubSpot.
Step 1: Open the Twilio setup
Sign in to Octopods and open the HubSpot workspace.
Click the option to add a new channel.
In the Add a Channel modal, select Twilio under Popular Channels.
If this is the first channel on the workspace that needs HubSpot’s Custom Channels permissions, Octopods shows a Re-authorize HubSpot prompt.
Step 2: Re-authorize HubSpot (if prompted)
Click the re-authorize button and sign in to HubSpot.
Approve the added permissions — the ones that let Octopods create and manage custom channels in your HubSpot inbox.
HubSpot redirects back to Octopods.
You only need to re-authorize once per workspace for this set of permissions.
Step 3: Enter Twilio credentials
In the Twilio setup form inside Octopods, fill in:
Twilio Account SID — starts with
ACand appears on the Twilio Console home page.Twilio Auth Token — also on the Twilio Console home page.
Use the Live credentials, not Test credentials.
Step 4: Pick the sender
Choose how outbound messages will be sent:
Phone Number — pick from the list of phone numbers Octopods fetches from your Twilio account. Each entry is a real E.164-formatted number on the account (for example,
+15551234567).Add Alphanumeric Sender ID — up to 11 characters (letters and digits). Alphanumeric senders can only send outbound messages and cannot receive replies, so pick this only if you do not need two-way conversations.
Short codes aren't supported. Use a long code (local or mobile), a toll-free number or an alphanumeric sender ID.
Step 5: Complete A2P 10DLC for US numbers
If your Twilio number is a US long code, US carriers require it to be registered under the A2P 10DLC framework. Unregistered traffic is heavily filtered.
You can create and register your A2P 10DLC brand and campaign from the Octopods dashboard. When you pick a US number, Octopods shows an A2P section with two options:
Register Brand in Twilio — opens the Twilio Console in a new tab, where you register your brand. Once the brand is registered, register your campaign in Octopods with the Register New Campaign form in the Twilio channel setup. Brand approval typically takes 1–2 weeks, and campaign approval another few days.
I’ll do this later — you can start using the channel right away for testing, but deliverability to US recipients will be poor until registration completes.
For numbers sending only to non-US countries, A2P 10DLC does not apply and this step does not appear.
Step 6: Save credentials
Click Activate Twilio Channel.
Octopods verifies your credentials against Twilio’s API.
On success, Octopods registers the webhook URL on your Twilio number automatically.
Step 7: Pick a HubSpot inbox and activate
Octopods opens the channel detail page with a Select HubSpot Inbox dropdown and an Activate button that is disabled until you pick an inbox.
Pick the inbox that should receive SMS conversations.
Click Activate.
Octopods registers the channel as a custom channel inside HubSpot.
The channel status changes to Active, and it appears in the workspace’s channel list.
Step 8: Send a test message
From a personal phone, text a short message to the Twilio number.
Open the HubSpot inbox you selected. A new conversation appears with your message.
Reply from HubSpot.
The reply arrives on your phone from the Twilio number.
Using a Twilio number that other tools already use
Twilio sends incoming messages for a number to one webhook URL. When you activate the channel, Octopods sets its own incoming-message URL and fallback URL on your Twilio number. That replaces the URLs that were set on the number before.
What this means for you:
Outbound messages from other tools keep working. Other tools send through the Twilio API, so they don’t use the incoming webhook.
Incoming replies go to Octopods, then to HubSpot. Any other tool that received replies through the old webhook stops receiving them.
Octopods can’t forward incoming messages to a second URL or keep an existing webhook. A number’s replies go to one place.
Before you connect a number that another tool uses, write down its current webhook URL in the Twilio Console (Phone Numbers > your number > Messaging configuration). If you need replies in that other tool too, use a separate Twilio number for Octopods.
Twilio SMS replies don’t appear in the HubSpot inbox
If your SMS deliver but customer replies never show up in HubSpot, work through these checks in order.
Check the webhook in Twilio. Open the number in the Twilio Console and look at the incoming message webhook. It must still be the URL Octopods set. If another tool or a teammate changed it, replies go there instead. To set it again, open the channel in Octopods, press Deactivate Twilio Channel, then activate the channel again. There’s no separate reconnect button, and only activating the channel registers the webhook again.
Check Twilio’s error logs. In the Twilio Console, open Monitor > Logs > Errors. A webhook error on an incoming message means Twilio couldn’t deliver the reply to the webhook URL. Note the error code and the time, then contact Octopods support.
Check the HubSpot inbox and seat. Make sure the channel is connected to the inbox you expect (Change the inbox on the channel detail page). Make sure your HubSpot account has a Professional or Enterprise GTM seat.
Check the sender. An alphanumeric sender ID can’t receive replies. Pick a phone number if you need two-way conversations.
Messages arrive in near real time, usually within seconds. Retries or provider rate limits can occasionally delay a message by a few minutes.
Replies sent the next day don’t appear
A reply that arrives after the HubSpot conversation was closed isn’t lost. With Open Closed Conversation Thread turned on, Octopods reopens the closed conversation. With it off, HubSpot starts a new conversation once the old one has been closed for more than 24 hours. Check the contact’s other conversations in the inbox. See Reopening Closed Conversations.
What’s different from Intercom
Compared to Setting Up Twilio SMS on an Intercom workspace, the HubSpot setup adds:
Re-authorizing HubSpot for Custom Channels permissions the first time.
Selecting a HubSpot inbox to route messages to before activating.
Credential entry, A2P handling, and webhook registration are identical.
Managing the channel
Change the inbox — open the channel detail page and pick a different inbox from the dropdown.
Rotate credentials — if you change the Auth Token in the Twilio Console, SMS stops working until you update it in Octopods. The token can’t be edited in place: the channel page shows Twilio Account SID and Twilio Auth Token read-only. Press Deactivate Twilio Channel, then activate it again, entering the new token in the Twilio Auth Token field and pressing Activate Twilio Channel. To keep the gap short, Twilio lets you create a secondary Auth Token: activate the channel with it first, then promote it to primary in the Twilio Console.
Track A2P status — campaign approval updates arrive in your Twilio Console. Until approved, expect degraded US delivery.
Common issues
“HubSpot re-authorization required” — HubSpot hasn’t granted the Custom Channels permissions. Follow the prompt.
Inbox dropdown is empty — create an inbox in HubSpot first.
“Credentials rejected” — double-check you’re using Live credentials, not Test.
“Credentials rejected” after you rotated the Auth Token — the old token stopped working when you changed it in Twilio. Deactivate the channel and activate it again with the new Auth Token. Check the Account SID too: it starts with
ACand must come from the same Twilio account as the number. Twilio subaccounts work, with their own Account SID and Auth Token.US messages not delivering — check A2P 10DLC registration status in Twilio.
What’s next
