Use the developer guides when you need to connect Hellotext with your own site, backend, CRM, commerce platform, or internal tools.
If you are connecting a custom store without a native integration, start with Integrate a custom store with Hellotext. It puts profiles, properties, products, historical orders, Hellotext.js, identity, and server-side tracking in the correct implementation order.
Most developer work in Hellotext falls into six areas:
- Integrating a custom store from end to end.
- Reading the API reference.
- Sending messages from your own system.
- Tracking customer activity.
- Defining business-specific actions and objects.
- Connecting unidentified sessions to customer profiles.
Before implementing, decide which part runs on your server and which part runs in the browser:
| Integration part | Data it uses |
|---|---|
| Server | Private business token to authenticate API requests. |
| Browser | Public Business ID to initialize Hellotext.js. |
| Synchronization | Hellotext IDs and your system references to identify each resource. |
Custom store integration
The custom-store guide is the practical starting point for a team that does not yet know which data belongs in the API, which activity belongs in Hellotext.js, or how the two sides connect.
Start here: Integrate a custom store with Hellotext.
API reference
The API reference is the source of truth for available resources, attributes, parameters, and endpoints.
Open the Hellotext API reference. Check the resource, method, required fields, data types, errors, and pagination before implementing a recipe. Store the IDs returned by Hellotext alongside your own system references; a display name does not replace the ID an endpoint requires.
API implementation recipes
Use the practical API guides when you need to move from the endpoint contract to a complete integration flow:
- Send messages with the API
- Create and send templates with the API
- Sync products and understand inventory availability
- Create and track orders with the API
- Create and track coupons with the API
- Troubleshoot a custom integration
Authentication
Private API requests use bearer tokens specific to the business where they were created. First confirm that you are in the business you want to integrate.
Open Settings, select Manage your authorization tokens, then Create new token and name it for the integration. The example shows only an unsaved fictional name; it contains no credential and does not confirm that a token was created.
After completing token creation in your own business, store the token in your server’s private configuration and send it in the Authorization header:
Authorization: Bearer YOUR_TOKEN
Never expose private tokens in browser code, public repositories, or client-side scripts. The Business ID used by Hellotext.js is public and has a different role: it does not authenticate private API requests. Distinguish that ID, the token name, and the secret token value.
Send messages from your system
Use the Messages API when your own system needs to send an individual free-form or template message through a compatible channel. Check the channel connection, permissions, recipient consent, and any template or conversation-window rules that apply to that channel.
A status: received response confirms receipt of the request, not message delivery. Verify the result in Hellotext before assuming it was sent; do not repeat a send only because your system did not receive a response in time.
Start with Send messages with the API. For SMS-specific length, encoding, costs, and limits, read Send SMS with the API.
Track customer activity
Use tracking when you want Hellotext to understand actions from your site, store, backend, or custom integration.
Track visitor navigation and interaction with Hellotext.js when the browser is the source. Track facts confirmed by your server, such as a payment, from your backend. Choose one source per occurrence to avoid duplicating the same event.
Tracked events can help you segment audiences, trigger playbooks or routes, attribute revenue, and give the inbox team more context. Each result depends on its data and configuration: receipt of a request does not prove that the event has been processed or that a sale has been attributed.
Keep reading: Tracking events for initialization and explicit recording. For a new installation using SDK 2.6.0, also follow the installation and browser-activity steps in the custom-store guide linked above: await initialization and explicitly track page.viewed once per navigation, without duplicating the first view.
Model business-specific activity
Use custom actions to name activity that Hellotext does not include by default. The action defines the activity type; an event records a specific occurrence. For example, defining appointment.booked does not record an appointment.
In Settings > Actions > Custom, the readable name “Appointment booked” and the tracking name appointment.booked represent the same fictional definition. Events use the exact tracking name; endpoints that manage the definition use its ID. Creating custom actions requires a compatible plan and permissions.
Use a profile property when the data describes the customer’s current state, such as their loyalty level. Use objects when the activity involves a reusable entity with its own properties and lifecycle, such as an appointment with a reference, date, and status.
Keep reading: Custom actions and Objects.
Connect browser sessions to customer profiles
Hellotext.js can create a session for unidentified visitors. To connect earlier activity, use the actual browser session ID and the correct profile ID in the same business. Verify the customer’s identity through your own system before attaching the session; do not assign a profile from an arbitrary ID supplied by the browser.
Identifying a profile and attaching a session does not grant consent to send messages. It also does not record a purchase or guarantee attribution on its own: those operations have their own requirements.
Keep reading: Tracking unidentified customers.