Health Navigator
Health Navigator is Abi’s conversational, AI-powered health assistant. It helps people explore health questions in natural language, understand possible next steps, and reach the information or service that is relevant to them. It is designed for health guidance, not formal diagnosis or treatment recommendations.
What it helps users do
Section titled “What it helps users do”Health Navigator is a single conversational entry point for health and wellbeing questions. It can help users understand symptoms and health concerns, explain preventive care or test-related questions, and find appropriate health information or local resources. The experience uses the ongoing conversation and any approved context to keep responses relevant and easy to follow.
It also connects guidance to action. Based on the partner’s setup, Health Navigator can signpost a user to an Abi service, a client portal, relevant web content, an external resource, or human support. This makes it useful not only for health guidance, but also for approved benefits navigation, eligibility, policy, and service-handoff journeys.
The service is available to users with an active subscription when it is enabled for the partner. The available journeys, content sources, actions, and escalation routes are agreed during implementation.
Product capabilities
Section titled “Product capabilities”| Capability | What it means for your product |
|---|---|
| Natural conversation | Users can express a health question in their own words rather than navigate a rigid symptom-checker flow. |
| Context-aware guidance | Partner-approved context can help tailor a conversation to the user’s situation and the services available to them. |
| Signposting and handoffs | The assistant can recommend resources, present a call to action, or route a user into an approved service or support channel. |
| Configurable journeys | Partners can define the content, services, actions, and rules that shape the experience for their users. |
What you can configure
Section titled “What you can configure”Health Navigator is not a generic chat window added beside your product. Its configuration defines what the assistant can recommend and how it should connect to your ecosystem. This can include:
- Client and Abi services that can be offered as next steps.
- Links to approved information, portals, product pages, or external resources.
- Action points your application can render or handle, such as a redirect or a client-side workflow.
- The context schema supplied when a conversation starts.
- The escalation path to a specialist or another support channel, where applicable.
Do not assume an action or resource is available just because it appears in another partner’s implementation. Render and handle only the message parts and actions enabled in your agreed configuration.
Conversation experience
Section titled “Conversation experience”Conversations are persistent chat sessions. A user starts or resumes a conversation, sends messages, and receives asynchronous replies. The API gives each conversation and message a stable identifier so your application can show the current thread, retrieve its history, and reconcile webhook delivery.
When starting a conversation, you can provide the partner-approved context needed for that journey. Supply only data that is necessary for the configured experience and matches the agreed schema.
Each conversation has a unique conversationId. Keep this identifier and include it in subsequent requests that address the conversation. It is also returned with conversation messages, which lets your application associate each message with the correct chat session.
Conversation states describe the lifecycle of a chat session:
| State | Meaning |
|---|---|
OPEN |
The conversation is active and messages can be sent and received. |
WAITING_FOR_RESPONSE |
Health Navigator is processing a response; wait for the reply before sending another message. |
RESOLVED |
Health Navigator has provided a final response or recommendation. The user may continue the conversation or start a new one, depending on the configured experience. |
CLOSED |
The conversation was closed by the user or automatically after inactivity. No further messages can be sent or received. |
By default, a conversation is automatically closed when no user message is received for 2 hours. It remains in the CLOSED state after that timeout, and no further input can be sent to the session.
Handle state transitions explicitly in the client so the interface does not offer actions that are unavailable for the current conversation state.
Integration lifecycle
Section titled “Integration lifecycle”- Start a conversation for an authenticated user.
- Send a user message and retain the returned identifiers.
- Receive replies through the configured webhook flow.
- Retrieve messages, conversation history, or a user’s conversations when needed.
- Close the conversation explicitly or allow the documented automatic closure after two hours of inactivity.
Starting a conversation
Section titled “Starting a conversation”The start-conversation endpoint creates a new Health Navigator chat session for the user identified in the path. You may provide an optional context object so the assistant can use approved information during that session, such as relevant user demographics, medical history, policy details, or other journey-specific data.
The shape and meaning of context are configured for each partner. The object must match the schema agreed during implementation; do not send arbitrary fields or sensitive information that is not required for the configured journey.
The response returns the userId and a conversationInfo object containing the new conversation id and its initial status. Persist the conversation identifier and use it for subsequent message, history, and close operations.
Messages, actionables, and resources
Section titled “Messages, actionables, and resources”A message is one atomic unit in a conversation. It can be sent by the user or Health Navigator and is identified by a ULID, timestamped, ordered, and composed of one or more content parts.
Each message includes a messageId, conversationId, sender role, content, and createdAt. Responses may also include updatedAt and protocolVersion. Keep the message and conversation identifiers returned by the API so your integration can retrieve the current history or reconcile asynchronous delivery.
The content.parts array preserves the order in which content should be presented. Supported part types include:
| Part | Purpose |
|---|---|
text |
Text from the user or assistant. |
image |
An image URL with an optional caption and media type. |
action |
The wire representation of an Actionable: a structured next step recommended by the assistant or selected by the user. |
resource |
Supporting information, such as an approved article or document. |
location |
A location object when the configured journey provides one. |
audio |
An audio URL with optional duration and media type. |
video |
A video URL with optional duration and media type. |
file |
A downloadable file with a name and media type. |
Your client should render and handle only the part types enabled for your agreed Health Navigator configuration.
Actionables
Section titled “Actionables”Actionables are structured suggestions made by Health Navigator based on the services and journey configured for your organization. They can direct the user to an Abi service, a client service, a client-side workflow, or another approved next step. The same actionable may be presented for the user to select or confirmed as part of the conversation.
In the API payload, an actionable is carried in a message part with type: action and an action object. The object can contain:
| Field | Meaning |
|---|---|
type |
The actionable category: abi_service, client_service, or action. |
name |
The configured identifier of the actionable. |
source |
Who supplied it: user, assistant or system. |
domain |
The configured domain, such as medical or administrative. |
referenceUrl |
Optional URL for additional context or a redirect. |
label |
Optional call-to-action label for client-side rendering. |
payload |
Optional additional data for the client workflow. |
postEffects |
Optional follow-up effects to apply after the actionable is handled. |
Resources
Section titled “Resources”Resources provide additional context or information related to the conversation. They can link to approved documents, images, articles, portals, or other relevant data.
A resource contains a required title and url, and may include an optional description. Validate and display resource URLs according to your agreed security and content policies.
Receiving Navigator updates
Section titled “Receiving Navigator updates”Health Navigator uses the same registration, authentication, retry, and idempotency rules as every other webhook event. Register the two Navigator event names in the webhook event catalog.
These deliveries use the Navigator v2 conversation envelope, rather than the response returned by /webhook/format-event:
| Event | Description |
|---|---|
conversationReplied |
Sent when Health Navigator replies to a message in an open conversation. |
conversationClosed |
Sent when a Health Navigator conversation closes manually or after inactivity. |
Use the event type and conversation identifier to route and reconcile a delivery. See the Navigator event payloads for the event attributes and examples.
Safe product boundaries
Section titled “Safe product boundaries”- Present Health Navigator as health guidance, not a replacement for clinical diagnosis, treatment, or emergency care.
- Use the escalation, privacy, retention, access-control, and presentation policies agreed for your implementation.
- Render only approved actions and resources, and preserve the meaning of the assistant’s content when displaying it.
See webhooks and callbacks and the API reference.