How do I connect my HubSpot CRM?

What the connection gives you

With HubSpot connected, two things happen. During a conversation, the person or company on the other side is looked up and their details appear next to the chat, for the bot and for your team. When a conversation closes, BotableX can write a ticket or contact activity back into HubSpot with the summary, the category, who handled it, and how it ended. Conversation states can also move a ticket along your pipeline.

Grant access

In HubSpot, create a private app and grant it the scopes shown on the BotableX Settings page under CRM. Each scope is tied to a feature: reading contacts and companies powers the lookup, writing tickets powers the export, and so on. If you only want lookups, you can grant only read scopes. Copy the token HubSpot gives you.

Test the connection

Back in BotableX, paste the token and press Test Connection. BotableX reports the portal id and the account type it sees. Check both before going further. Connecting to a production portal by mistake and enabling writes is the one error that is hard to undo, so start with a sandbox or developer test portal.

Refresh Schema

Press Refresh Schema. BotableX now reads your portal’s own vocabulary: every contact, company and ticket property, every pipeline and stage, and every owner. This is what fills the dropdowns in the next step. If the mapping screen looks empty, this step has not run yet.

Choose your customer model

Some businesses serve private individuals; each customer is a contact. Others serve companies; each customer is a company with several contacts. Choose the model that matches your CRM. It decides which record the bot looks up and which record the conversation is written to.

Map fields

Your portal has its own names for things. BotableX has a fixed list of fields it produces, such as the conversation category, the summary, the channel, who handled it, the customer’s email, and the company id. Mapping is where you say, once, which of your properties means which of ours.

Two rules make this reliable:

• Every field is a dropdown filled from your real portal. You cannot type a property name, because a single mistyped character produces a property that matches nothing and fails silently. The same rule applies to stage ids, pipeline ids and owner ids. Use the pickers.
• Nothing is guessed. If a field is not mapped, the feature that needs it reports “not configured” and stops. It never picks a likely property. A wrong guess would write into your CRM and look like it worked.

Switch on writes

Writes are off by default. Turn them on one at a time: contact or company update, ticket creation, pipeline stage sync. After each, run one test conversation end to end and open the record in HubSpot. The Export Ledger in BotableX lists every write attempt, its result, and lets you retry a failed one after fixing the cause.

If a lookup finds nobody

Check that the identity field is mapped to the property that actually holds the value your customers give (email, phone, or an external id), and that Refresh Schema has run since that property was created. Most “customer not found” reports come down to those two.