Zia Assistant

Purpose

The Assistant API can answer user queries about your organization-specific information as well as general, globally available topics. To receive contextual responses, add your organization’s details in the chat_history JSON array. The AI will use the chat_history's information to generate a structured response.

Prerequisite:

To enable AI configuration, go to Setup > Zia > Smart Prompt > Enable any one of the LLM vendors.

Note: Apart from Zia LLM, all other LLM vendors require a purchased API key to be enabled and used within Zoho CRM.

Endpoint

POST /zia/smart_prompt/assistant

Request Details

Request URL

{api-domain}/crm/{version}/zia/smart_prompt/assistant

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.intelligence.CREATE

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/zia/smart_prompt/assistant"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d zia.json

Input JSON

assistantJSON object, mandatory
Specify the smart prompt configuration details that define how the prompt should be processed.
- chat_historyJSON array, mandatory
  Specify the role and conversation context between the user and the assistant.
  
  This context helps the assistant create and maintain multi-turn conversations. You can also provide a set of questions and answers in the chat_history. This helps train the AI to understand your business context and prior discussions. You can include your organization based details in the chat_history.
  When a related question is asked, the assistant refers to the provided information in the chat_history to generate more accurate replies.
  - rolestring, mandatory
    Specify who is initiating the conversation.
    Possible Values: user, assistant
  - contentstring, mandatory
    The actual message or text exchanged during the conversation.
    Train your AI by providing your organization based questions and answers. This helps the assistant understand your business context and improves response accuracy.
  Note: If you ask general or global questions whose answers are widely available on the internet, the AI can still respond correctly even without prior chat history.
- prompt_settingsJSON object, optional
  Specify how the assistant should structure the enriched response.
  - lengthstring, mandatory
    Specify the expected length of the generated prompt.
    Possible values : Single Sentence, Short Paragraph, Medium Paragraph, Long Paragraph, A Few Paragraphs, Bulleted List, Numbered List, Detailed Explanation, Summary, In-depth Analysis, Brief Note, Overview, Quick Guide, Extended Essay.
  - stylestring, mandatory
    Define the tone of the prompt.
    Possible values : Casual, Persuasive, Enthusiastic, and Professional.
- promptstring, mandatory
  The main input or question that you or your customers want to ask the AI assistant.
  You can use this field to ask either:
  - Organization-based questions - Users can ask organization-specific questions. The assistant will rely only on the information you include in the chat_history JSON array to provide accurate and relevant responses.
  - Global or common questions - General queries whose answers are publicly available on the internet, such as common facts, definitions, or widely known information.

Note

You can enable only one AI vendor at a time in Zoho CRM. Make sure an AI vendor is enabled to receive enriched responses from the assistant.
The Smart Prompt Builder API does not store any of the questions, answers, or chat history you send. All processing happens only for that specific request, using the data you provide in the chat_history JSON array.
- The system does not:
  - Retain previous API requests
  - Retain previous API responses
  - Store conversation history
The chat_history field has no limit.
One prompt can be given in a single API call.

Sample Input

Copied{
    "assistant": {
        "chat_history": [
            {
                "role": "user",
                "content": "Who is the primary contact for BrightEdge Inc.?"
            },
            {
                "role": "assistant",
                "content": "The primary contact is James Lee, Head of Procurement."
            },
            {
                "role": "user",
                "content": "What industry does BrightEdge Inc. operate in?"
            },
            {
                "role": "assistant",
                "content": "BrightEdge Inc. operates in the Software and IT Services industry."
            },
            {
                "role": "user",
                "content": "Does this lead have any open deals?"
            },
            {
                "role": "assistant",
                "content": "Yes, there is one open deal associated with this lead."
            }
        ],
        "prompt_settings": {
            "length": "Single Sentence",
            "style": "Professional"
        },
        "prompt": "Who is the main contact for BrightEdge Inc.?"
    }
}

Possible Errors

INVALID_DATAHTTP 204
Invalid data
Resolution:
- Invalid value has been given in the role key. Provide valid values.
  Possible values: user and assistant
- The length key's value is invalid. Provide a valid value.
  Possible values: Single Sentence, Short Paragraph, Medium Paragraph, Long Paragraph, A Few Paragraphs, Bulleted List, Numbered List, Detailed Explanation, Summary, In-depth Analysis, Brief Note, Overview, Quick Guide, Extended Essay
- The style key's value is invalid. Provide a valid value.
  Possible values: Casual, Persuasive, Enthusiastic, Professional
MANDATORY_NOT_FOUNDHTTP 400
One or more mandatory keys are missing
Resolution: Specify all the required fields to allow the AI assistant to process your request.
Refer to Input JSON section to know the mandatory fields.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL.
Specify a valid request method. Refer to Endpoints section.
FEATURE_NOT_ENABLEDHTTP 400
Feature not enabled
Resolution: Enable any one LLM vendor to use the Smart Prompt feature. To enable, go to Setup > Zia > Smart Prompt and select an LLM vendor.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to create a prompt. Create a new token with valid scope. Refer to Scope section.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the Request URL section above.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "assistant": {
        "code": "SUCCESS",
        "details": {
            "data": "The primary contact for BrightEdge Inc. is James Lee, Head of Procurement."
        },
        "message": "Query made successfully",
        "status": "success"
    }
}