---
description: A brief overview of the conversational flow
---

# Quick Start Conversation

## Introduction

This guide provides a concise overview of how to engage in a conversation with the Nutrition Advisor using the API. It includes code examples in Python to help you get started quickly.

This guide assumes you have read and executed the [Authorization Process](../rest-docs/authorization-flow) and [Request Setup](../rest-docs/api-request-setup). All requests in code examples pass an undefined `headers` which you can quickly build following the steps in the above guides.

## The Response Object

All responses from the Nutrition Advisor will be returned in the `AdvisorResponse` object format:

| Field              | Type                    | Description                                                                                                                                             |
| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `threadId`         | string                  | The unique identifier of the conversation thread.                                                                                                       |
| `messageId`        | string                  | The unique identifier of the advisor's response message.                                                                                                |
| `content`          | string                  | The main content of the advisor's response. Empty if message has a `dataRequest` or `actionResponse`. Should be JSON decoded from string when received. |
| `contentToolHints` | \[]string               | An array of tool names (or empty) that the advisor has sensed could be useful to run on this response.                                                  |
| `dataRequest`      | `AdvisorDataRequest`    | If the advisor requires additional information, this field contains the details of the data request.                                                    |
| `actionResponse`   | `AdvisorActionResponse` | If the advisor performs an action based on the message, this field contains the details of the action response.                                         |
| `usage`            | `AdvisorResponseUsage`  | Information about the token usage for the response.                                                                                                     |

## List Available Tools

To list the available tools, make a GET request to `/v2/products/nutrition-advisor/tools`. The response will include an array of tool objects with the following fields:

| Field         | Type   | Description                                                |
| ------------- | ------ | ---------------------------------------------------------- |
| `name`        | string | The unique name of the tool.                               |
| `displayName` | string | The display name of the tool.                              |
| `description` | string | A brief description of what the tool does.                 |
| `type`        | enum   | The type of the tool: `target`, `inputsense`, or `vision`. |

#### Code Example

```python
import requests

url = "https://api.passiolife.com/v2/products/nutrition-advisor/tools"
response = requests.get(url, headers=headers)
tools = response.json()

# Store tools for future reference
cached_tools = {tool["name"]: tool for tool in tools}
```

## Start A Conversation Thread

To start a new conversation, make a POST request to `/v2/products/nutrition-advisor/threads`. You can optionally include the `?plainText=true` query parameter to receive plain text responses without markdown formatting.

#### Code Example

```python
import requests

url = "https://api.passiolife.com/v2/products/nutrition-advisor/threads?plainText=false"
response = requests.post(url, headers=headers)
advisor_response = response.json()

thread_id = advisor_response["threadId"]
```



## Interraction Flow

When you receive an `AdvisorResponse` back from the Nutrition Advisor, follow these steps:

#### 1. Check if `content` is non-empty (Lines 2-17)

* If so, parse `contentToolHints`.
* If any tools are found, match them to the `name` field of a cached available tool.
* Use a switch statement based on the tool name to handle specific cases.
* For example, if the tool name is "SearchIngredientMatches", make a call to the `target` tool type using the message.

#### 2. Check if `dataRequest` is not null (Lines 19-40)

* If not null, parse the `name` field and use a switch statement to handle specific cases.
* For example, if the tool name is "DetectMealLogsRequired" and the `parameters` field contains `daysBack: 1`, respond to the data request with the appropriate meal log data.

#### 3. Check if `actionResponse` is not null (Lines 41-48)

* If not null, parse the `name` field and use a switch statement to handle specific cases.
* For example, if the tool name is "SearchIngredientMatches", parse the `data` field as JSON to obtain an array of ingredient data.

#### Code Example

{% code lineNumbers="true" %}
```python
def handle_advisor_response(advisor_response, thread_id, cached_tools):
    # check the advisor for `content`. This is its text-response to the chat
    # If a value exists here, no value will exist in either
    # `dataRequest` or `actionResponse`
    if advisor_response["content"]:
        content = json.loads(advisor_response["content"])
        tool_hints = advisor_response["contentToolHints"]
        
        for tool_name in tool_hints:
            if tool_name in cached_tools:
                if tool_name == "SearchIngredientMatches":
                    tool_url = f"https://api.passiolife.com/v2/products/nutrition-advisor/threads/{thread_id}/messages/tools/target/{tool_name}"
                    tool_response = requests.post(tool_url, json={"messageId": advisor_response["messageId"]}, headers=headers)
                    
                    # Recursively handle the response from the tool request
                    handle_advisor_response(tool_response.json(), thread_id, cached_tools)
                    return
                    
    # If we sent a message with InputSense tools enabled, the response might
    # contain `content`, if no input sense tools were detected as necessary.
    # otherwise, `content` is empty and `dataRequest` is filled, containing
    # info on the data you need to proivde
    if advisor_response["dataRequest"]:
        data_request = advisor_response["dataRequest"]
        
        if data_request["name"] == "DetectMealLogsRequired":
            parameters = json.loads(data_request["respondParameters"])
            days_back = parameters["daysBack"]
            
            respond_url = f"https://api.passiolife.com/v2/products/nutrition-advisor/threads/{thread_id}/messages/{advisor_response['messageId']}/respond"
            respond_data = {
                "data": "...",
                "runId": data_request["runId"],
                "toolCallId": data_request["toolCallId"]
            }
            respond_response = requests.post(respond_url, json=respond_data, headers=headers)
            
            # Recursively handle the response from fulfilling the data request
            handle_advisor_response(respond_response.json(), thread_id, cached_tools)
            return

    # If we sent a tool request, parse actionResponse to retrieve its data
    if advisor_response["actionResponse"]:
        action_response = advisor_response["actionResponse"]
        
        if action_response["name"] == "SearchIngredientMatches":
            ingredient_data = json.loads(action_response["data"])
            # ... do something with the ingredient data
            
```
{% endcode %}
