Hi everyone,
I posted a question in the community earlier but haven’t received a response yet, so I wanted to ask again here.
I’m currently trying to use the HubSpot Custom Channel API, but the conversations.custom_channels scopes are grayed out in my app. When I hover over them, I see the following message:
“Your account doesn’t have access to this scope.”
My account has Super Admin permissions, but I’m still unable to select these scopes.
Does anyone know:
- Which HubSpot subscription or account type is required to access the Custom Channel API?
- Is there any additional configuration or approval required to enable these scopes?
- Is access to
conversations.custom_channels restricted to certain HubSpot plans or accounts?
Our use case is to build a custom chat UI integrated with HubSpot Inbox, so we need access to the Custom Channel API.
Any information or experience with this would be greatly appreciated.
Thanks!
Hi @trieu.bui and welcome, we are so glad you are here!
Great question, thanks for asking the HubSpot Community!
Not sure what happened with the other post you created, I cannot find it online. There might have been a glitch when posting?
When checking on this documentation " Scopes - HubSpot docs ", I can see that the Custom Channels API requires Sales Hub Professional or Service Hub Professional (or higher) on the account. I see that you are a free user so that’s why the conversations.custom_channels.read/.write scopes are grayed out.
Also note: custom channels can only be defined/registered via a proper app you create, not through legacy private apps, since those endpoints aren’t supported there.
Please let us know if you have additional questions, we are here for you! 
Have a wonderful day!
Bérangère
Hi Bérangère,
Thank you for the clarification!
Before we consider upgrading our HubSpot plan, I’d like to confirm one thing about the Custom Channels API.
Our goal is to build our own custom chat UI on our website, while using HubSpot Inbox for our support team. Specifically:
-
Customers would chat through our own custom UI.
-
The conversation would be sent to HubSpot via the Custom Channels API.
-
Our support/admin users would receive and reply to the conversation directly from HubSpot Inbox.
-
The replies from HubSpot would then be delivered back to our custom chat UI.
Could you please confirm whether this workflow is fully supported by Custom Channels API with a Sales Hub Professional or Service Hub Professional plan?
If yes, we would consider upgrading our plan to enable this functionality.
Thank you!
Super Admin on the portal is not enough for those scopes. HubSpot gates conversations.custom_channels.read / .write to Sales Hub or Service Hub Enterprise on the account where the app is installed. Free / Starter / Pro usually show them grayed out with exactly that hover text.
Practical checklist:
- Confirm the target HubSpot account is Sales Hub Enterprise or Service Hub Enterprise.
- Use a public OAuth app (developer platform). Legacy private apps are not supported for Custom Channels registration.
- Request conversations.custom_channels.read, .write, and conversations.read. Add contact write only if you need email capture from the channel.
- If you are building on a non-Enterprise sandbox, scopes stay locked until you use an Enterprise test portal (or client portal).
If you share whether the grayed portal is Free/Pro/Enterprise, the next step is either upgrade / Enterprise test account or Hub refresh after Enterprise is live.
VK | AXIOPRAX
Hi @trieu.bui and thanks for sharing the context and goal with us!
And thanks to @kishoreaxioprax for your contribution!
Yes, this workflow is fully supported! Please note that you’ll need to build an app to register the custom channel, as the custom channel endpoints aren’t supported for legacy private apps.
I’d love to hear from our Top Experts: Hi @evaldas and @Anton do you have insights to share with @trieu.bui on which steps to take to reach this goal, please?
Enjoy the day and thanks so much!
Bérangère
Hi Bérangère and Top Experts,
Thank you for confirming that this workflow is fully supported.
I’ve reviewed the Custom Channels documentation, but I’m still having some difficulty understanding the overall flow from an implementation perspective.
Could you please provide a simple step-by-step overview of the recommended flow for a Custom Channels integration, starting from creating the HubSpot App through to handling customer messages and admin replies?
It would be especially helpful to understand:
- What needs to be created/configured during the initial setup.
- How the Custom Channel is connected to a HubSpot Inbox.
- How an external customer message enters HubSpot and becomes a conversation in the Inbox.
- How an admin reply from the Inbox is delivered back to the external application.
- How the external application should identify and map the customer/conversation throughout this process.
- Which components are handled by HubSpot and which components need to be implemented by the external application/backend.
A simple flow diagram or numbered sequence would be greatly appreciated.
Thank you!
Hi @trieu.bui and thanks for following up with us!
Here is a step-by-step implementation flow:
- Create an app: Build it as a public/developer-platform app. Here are the request scopes:
conversations.custom_channels.read, conversations.custom_channels.write, conversations.read, and optionally crm.objects.contacts.write for auto-contact-creation. Note your App ID, Client ID, and Client secret.
- Register your custom channel:
POST /conversations/v3/custom-channels (using your developer API key + App ID) with a name, capabilities object (threading model, delivery identifier types, attachment support, rich text, etc.), and optionally a webhookUrl.
- Connect a channel account to an inbox: Either directly via
POST /conversations/v3/custom-channels/{channelId}/channel-accounts (specifying inboxId and a deliveryIdentifier), or by building a marketplace-style connection setup flow using channelAccountConnectionRedirectUrl/staging tokens if distributing to multiple customers.
- Customer message → HubSpot: when your external service receives a message, your backend calls
POST /conversations/v3/custom-channels/{channelId}/messages with messageDirection: "INCOMING", channelAccountId, senders/recipients (using delivery identifiers), and integrationThreadId (if using that threading model). HubSpot logs it as a conversation thread in the Inbox/help desk and creates/matches a CRM contact.
- Admin reply → external app: when a HubSpot user replies in the Inbox, HubSpot
POSTs an OUTGOING_CHANNEL_MESSAGE_CREATED event to your registered webhookUrl, containing the message content, channelAccountId, and thread/identifier info. Your backend receives this and delivers the message to your custom chat UI.
- Mapping customers/conversations: identity is tracked via
deliveryIdentifier (email, phone, or an opaque CHANNEL_SPECIFIC_OPAQUE_ID like a username/UUID) plus either your own integrationThreadId or HubSpot-managed thread IDs (depending on threadingModel).
- Division of responsibility: HubSpot handles the Inbox UI, agent assignment, CRM contact/thread storage, and webhook delivery. You (external backend) must host the chat UI, manage the webhook receiver, publish incoming messages, and maintain your own mapping of delivery identifiers/thread IDs to your internal conversation records.
Hi @Anton, @kishoreaxioprax and @evaldas, do you have best practices or tips to share with @trieu.bui, please?
Thank you and please let us know if you need more information!
Bérangère
This post was created with the assistance of AI tools
Thank you, Bérangère, for the detailed step-by-step guidance! I’ve followed the flow and successfully got the custom channel working. Really appreciate your help and everyone’s support in the community!
That’s great news @trieu.bui! 
Thanks so much for coming back and sharing the update, I’m glad to hear you got the custom channel up and running successfully.
Happy to help, and thanks for being part of the Community! 
Wishing you a lovely weekend!
Bérangère